# Nat20 Notes — agent guide

## Commands

- `docker compose up -d --build` — build & launch both services (backend :8000, frontend :8020)
- `cd frontend && npm run dev` — Vite dev server (proxies `/api` → `localhost:8000`)
- **No tests, no lint/typecheck scripts exist.** Don't look for them.

## Architecture

- Two Docker Compose services: `backend` (Python 3.11, FastAPI, SQLite, WhisperX as lib) and `frontend` (React 18 + Vite + Tailwind, served by nginx which proxies `/api` → backend).
- Data lives in Docker volume `app_data` at `/data` (SQLite DB + `uploads/audio/transcripts/notes` subdirs). No external DB.
- Background jobs (transcribe, summarize) run via in-process `ThreadPoolExecutor(max_workers=2)` — no Redis/Celery.
- Frontend serves on port **8020** (d20 nod).

## Critical convention: flat settings schema

Settings are a flat key/value table in SQLite. **Every layer must share exact same keys:**
`backend/app/config.py:DEFAULT_SETTINGS`, `frontend/src/api.ts:AppSettings`, the settings router, and Setup/Settings pages. Changing a key without updating all layers silently desyncs the UI.

## Docker / framework quirks

- Torch pinned to `2.3.1` with `cu121` wheels (`--extra-index-url https://download.pytorch.org/whl/cu121`) — cuDNN ABI compat with `ctranslate2`. Don't bump unpinned.
- Backend Dockerfile is two-stage (builder + runtime). ffmpeg required in runtime for audio extraction.
- nginx `client_max_body_size` 500M, proxy timeouts 3600s. Files >15MB auto-chunked by frontend `createSession()`.
- Frontend changes in Compose mode require a rebuild (`docker compose up -d --build`). Vite dev server is for local-only dev.

## Tailwind theme

Custom colors (`deep`, `panel`, `brass`, `ember`, etc.) and fonts (`Fraunces`, `Inter`, `IBM Plex Mono`) in `tailwind.config.js`. Reusable component classes in `frontend/src/styles.css` (`.card`, `.btn-primary`, `.btn-secondary`, `.input`, `.eyebrow`) — use these over raw Tailwind utilities.

## Constraints

- Requires NVIDIA Container Toolkit + HuggingFace token for speaker diarization.
- First run: setup wizard, then `onboarding_completed` flag gates access to main UI.
- Default Ollama endpoint: `http://localhost:11434`.