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:

Browser connects via HTMX WebSocket to /ws/price or /ws/strike
btcprice proxies to btcdata's /api/price/ws or /api/strike/ws
JSON from btcdata is transformed into HTML fragments (in price_json_to_html / strike_json_to_html)
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

2.1 KiB Raw Blame History