# Lumière

Lumière is a personal cinema diary. Track films you've watched, queue films to watch, and record ones you've set aside. Built with FastAPI and SQLite — no build step, no framework overhead, just a fast server-rendered app.

## Features

- **Three shelves** — Diary (watched), Queue (to watch), Abandoned (set aside)
- **TMDB integration** — search and auto-populate poster, director, runtime, genre, cast, overview
- **Third-party ratings** — IMDb, Rotten Tomatoes, and Metacritic scores via OMDb on each film detail page
- **Director pages** — all films by a director, with bio and photo from TMDB
- **Statistics** — all-time stats (country map, decade breakdown, star distribution, activity heatmap) and year-in-review
- **CSV import** — Letterboxd diary and watchlist imports with deduplication and TMDB enrichment
- **Password-protected** — single-owner login via argon2; public read-only profile at `/tyler`
- **Infinite scroll + search** — live search and load-more across all shelves
- **Responsive** — cinematic dark theme, works on desktop and mobile

## Tech Stack

- **Backend:** [FastAPI](https://fastapi.tiangolo.com/) (Python)
- **Database:** [SQLite](https://www.sqlite.org/) via [SQLAlchemy](https://www.sqlalchemy.org/) ORM
- **Frontend:** Jinja2 templates, CSS custom properties, vanilla JS (no build step)
- **APIs:** [TMDB](https://www.themoviedb.org/documentation/api) for metadata, [OMDb](https://www.omdbapi.com/) for ratings

## Getting Started

### Prerequisites

- Python 3.10+
- TMDB API key (free at themoviedb.org)
- OMDb API key (free tier at omdbapi.com)

### Installation

1. Clone and enter the repo:
   ```bash
   git clone <your-repo-url>
   cd lumiere
   ```

2. Create a virtual environment and install dependencies:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   ```

3. Create a `.env` file:
   ```env
   TMDB_API_KEY=your_tmdb_key
   OMDB_API_KEY=your_omdb_key
   SESSION_SECRET=some-long-random-string
   OWNER_PASSWORD_HASH=...
   ```

   Generate the password hash:
   ```bash
   python -c "from argon2 import PasswordHasher; print(PasswordHasher().hash('your-password'))"
   ```

4. Run the app:
   ```bash
   uvicorn main:app --reload
   ```

Open `http://127.0.0.1:8000` and log in.

## Project Structure

```
main.py           # App entry, middleware, router registration
models.py         # Film ORM model
database.py       # SQLite engine, self-healing schema migration
routers/
  films.py        # Shelf views, CRUD, director page, ratings API
  imports.py      # Letterboxd/watchlist CSV import
  stats.py        # All-time stats and year-in-review
  auth.py         # Login/logout
  profile.py      # Public profile page
  tmdb.py         # TMDB search proxy for autocomplete
  about.py        # About page
services/
  tmdb.py         # TMDB API client
  omdb.py         # OMDb ratings client
  film_people.py  # Name normalization, slug helpers
  countries.py    # ISO country code mapping
templates/        # Jinja2 HTML templates
static/           # CSS, JS, icons
```