49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# 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
|