1 files changed, 75 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6c1807f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# 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.
+
+## 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.
+
+## 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)
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.10+
+- A TMDB API Key
+
+### Installation
+
+1. **Clone the repository:**
+   ```bash
+   git clone <your-repo-url>
+   cd lumiere
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Set up environment variables:**
+   Create a `.env` file in the root directory and add your TMDB API key:
+   ```env
+   TMDB_API_KEY=your_api_key_here
+   ```
+
+5. **Run the application:**
+   ```bash
+   uvicorn main:app --reload
+   ```
+
+The application will be available at `http://127.0.0.1:8000`.
+
+## 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]