1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
# 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
```
|
