1 files changed, 51 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a646370
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+Lumiere is a personal cinema diary — a server-rendered FastAPI web app backed by SQLite. Users track films across three shelves: `diary`, `queue`, and `abandoned`. TMDB enriches film metadata (posters, directors, runtime, countries).
+
+## Commands
+
+```bash
+# Setup
+python -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# Run dev server
+.venv/bin/uvicorn main:app --reload
+
+# Syntax check (run before any PR)
+.venv/bin/python -m py_compile main.py database.py models.py routers/*.py services/*.py
+
+# Tests (no suite yet — use pytest when adding tests)
+.venv/bin/pytest
+```
+
+Requires a `.env` file with `TMDB_API_KEY=...`. App runs at `http://127.0.0.1:8000`.
+
+## Architecture
+
+**Request flow:** Browser → FastAPI router → SQLAlchemy (SQLite) → Jinja2 template → HTML response. `static/app.js` handles star ratings (JSON PATCH) and TMDB search autocomplete without a build step.
+
+**Key files:**
+- `main.py` — app entry, router registration
+- `database.py` — SQLite engine, sessions, self-healing schema migration (no Alembic; renames old table on column mismatch and migrates data)
+- `models.py` — single `Film` ORM model with a `shelf` column
+- `routers/films.py` — shelf listing, CRUD, director page, queue random pick, star rating API
+- `routers/imports.py` — Letterboxd and watchlist CSV import, deduplication, enrichment
+- `routers/stats.py` — all-time stats and year-in-review (pure Python aggregation, no SQL GROUP BY)
+- `routers/tmdb.py` — `/tmdb/search?q=` proxy for JS autocomplete
+- `services/tmdb.py` — TMDB API client: search, detail fetch, metadata application
+- `services/film_people.py` — director name normalization and URL slug helpers
+
+**Patterns:**
+- Route logic stays in `routers/`, shared service logic in `services/`
+- Stats computed in-memory from full query results (appropriate for personal-scale SQLite)
+- TMDB fields are additive/optional; all core film fields work without enrichment
+- Import pipeline dedupes by TMDB ID first, then normalized title+year+date
+
+## Coding Conventions
+- 4-space indentation; `snake_case` for functions/variables, `PascalCase` for ORM models, uppercase for shelf/status constants
+- Jinja templates stay minimal; defer behavior to `static/app.js`
+- `lumiere.db` and `*.db.bak-*` files are local artifacts — do not drive code changes from them