# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

Bitcoin price tracker UI — Python FastAPI web application. Serves an HTML/Tailwind page with live price updates streamed from btcdata (separate service) via WebSocket using HTMX.

## Build & Development Commands

- `make run` — Start dev server on port 4000 (connects to btcdata at BTCDATA_URL from `.env`)
- `make run-local` — Start dev server using BTCDATA_LOCAL_URL from `.env`
- `make tailwind` — Watch Tailwind CSS for changes (run in separate terminal)
- `make test` — Run tests with pytest (`tests/` directory)
- `npm run css:build` — One-off Tailwind CSS build

## Docker

Docker runs alongside local dev on different ports:

| Service  | Local dev      | Docker         |
|----------|----------------|----------------|
| btcprice | localhost:4000 | localhost:4041 |
| btcdata  | localhost:4100 | localhost:4101 |

Uses external `btc-network` Docker network. btcdata must be running separately (or via its own docker-compose).

## Architecture

- **Framework:** FastAPI + Uvicorn
- **Templates:** Inline HTML strings in Python + HTMX (WebSocket extension)
- **Styling:** Tailwind CSS v4 — scans `app/**/*.py` for class names (configured in `resources/css/input.css` via `@source`)
- **Data backend:** btcdata (separate service at BTCDATA_URL, default http://localhost:4100)
- **No database** — all data comes from btcdata

### Data Flow

btcprice acts as a WebSocket proxy between the browser and btcdata:
1. Browser connects via HTMX WebSocket to `/ws/price` or `/ws/strike`
2. btcprice proxies to btcdata's `/api/price/ws` or `/api/strike/ws`
3. JSON from btcdata is transformed into HTML fragments (in `price_json_to_html` / `strike_json_to_html`)
4. HTMX swaps the HTML into the DOM by matching element IDs (`price-display`, `strike-display`)

### Key Conventions

- Numbers use Danish locale formatting (dots for thousands, commas for decimals) via `da_fmt()`
- Price changes are color-coded: green (up), red (down), gray (unchanged)
- All HTML is built as string concatenation in Python — no template engine