diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 87 |
1 files changed, 50 insertions, 37 deletions
@@ -1,75 +1,88 @@ # Lumière -Lumière is a personal cinema diary and film catalog application. Built with FastAPI and SQLAlchemy, it allows you to track movies you've watched, manage a queue of films to watch, and maintain a "deserted" list of films you no longer intend to see. +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 -- **Personal Diary:** Keep a detailed record of movies you've watched, including dates, notes, and ratings. -- **Film Shelves:** Organise films into three distinct categories: - - **Diary:** Films you have watched. - - **Queue:** Films you intend to watch. - - **Abandoned:** Films you have decided not to watch. -- **TMDB Integration:** Seamlessly import movie data from The Movie Database (TMDB) to populate your collection. -- **Statistics:** Track your viewing habits and film statistics. -- **Responsive Design:** A cinematic, dark-themed interface optimized for both desktop and mobile. +- **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/) with [SQLAlchemy](https://www.sqlalchemy.org/) ORM -- **Frontend:** Jinja2 templates, CSS (Modern CSS Variables), and Vanilla JavaScript -- **Data Source:** [The Movie Database (TMDB) API](https://www.themoviedb.org/documentation/api) +- **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+ -- A TMDB API Key +- TMDB API key (free at themoviedb.org) +- OMDb API key (free tier at omdbapi.com) ### Installation -1. **Clone the repository:** +1. Clone and enter the repo: ```bash git clone <your-repo-url> cd lumiere ``` -2. **Create a virtual environment:** +2. Create a virtual environment and install dependencies: ```bash python -m venv .venv - source .venv/bin/activate # On Windows use: .venv\Scripts\activate - ``` - -3. **Install dependencies:** - ```bash + source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt ``` -4. **Set up environment variables:** - Create a `.env` file in the root directory and add your TMDB API key: +3. Create a `.env` file: ```env - TMDB_API_KEY=your_api_key_here + 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'))" ``` -5. **Run the application:** +4. Run the app: ```bash uvicorn main:app --reload ``` -The application will be available at `http://127.0.0.1:8000`. +Open `http://127.0.0.1:8000` and log in. ## Project Structure -- `main.py`: Application entry point and FastAPI configuration. -- `models.py`: SQLAlchemy database models. -- `database.py`: Database connection and initialization. -- `routers/`: API route handlers (films, imports, stats, tmdb). -- `services/`: Business logic and external API integrations (TMDB). -- `templates/`: Jinja2 HTML templates. -- `static/`: Static assets (CSS, JS, images). -- `lumiere.db`: SQLite database file. - -## License - -[Specify License, e.g., MIT] +``` +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 +``` |