Instruction file imported from shammy642/led_manager (.github/instructions/overview.instructions.md). Copyright stays with the author.

Architecture overview

Server-rendered FastAPI app: Jinja2 templates + HTMX partial swaps, not a JSON API. Non-HTML surfaces are the monitor WebSockets (/ws/monitor/*) and the Settings SQLite export download.

Layers (top → bottom)

1. Routes (app/webapp_routes/) — thin. Parse forms, coordinate services/CRUD, render templates. Never contain SQL or database-transfer implementation details.
2. CRUD (app/crud/) — one module per entity (receiver_crud.py, device_crud.py, player_crud.py). Functions take session: Session first, return models, raise domain errors.
3. Models (app/models/) — SQLModel tables with Pydantic validators. Own all field validation/normalization.
4. Services (app/services/) — external-system integrations (dnsmasq, arp, ping, update) plus the SQLite-only database transfer boundary. Services never import routes or CRUD. database_transfer.py deliberately imports the SQLModel types only to validate imported rows before installation.
5. Utils (app/utils/) — shared helpers (exceptions, formatting, form parsing, config writers). No imports from crud/routes/services.

Normal dependency direction is downward: routes → crud → models and routes → services → utils. The database transfer service is a lifecycle exception: it receives the database path and engine callbacks, and imports models for snapshot validation; it must remain independent of routes, CRUD, monitoring, and dnsmasq. CRUD modules may import each other for FK checks (e.g. receiver_crud calls device_crud.get_device; use a function-local import to avoid cycles, as in device_crud._validate_player_id).

Sync vs async

• Route handlers and CRUD are sync (SQLite via check_same_thread=False).
• Async only around monitoring: MonitorHub, PingManager, PingProbe, WebSocket routes, and the monitor start/stop button routes.
• MonitorHub is a module-level singleton via get_monitor_hub(); tests reset it with reset_monitor_hub_for_tests().

Directory ownership

Where new code goes

App wiring

app/app.py creates the FastAPI(lifespan=...) app (lifespan calls create_db_and_tables()), mounts /static, includes every router including settings_router, and redirects / → read_monitor. New routers must be imported and included there.