diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bf95f64 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,22 @@ +# Repository Guidelines + +## Project Structure & Module Organization +`main.py` boots the FastAPI app and includes routers. `database.py` manages the SQLite engine, sessions, and schema setup. `models.py` defines the `Film` ORM model. Route handlers live in `routers/` (`films.py`, `imports.py`, `stats.py`, `tmdb.py`), and TMDB integration logic lives in `services/tmdb.py`. Server-rendered UI templates are in `templates/`; browser assets are in `static/`. Local data files such as `lumiere.db` and backup snapshots stay at the repo root and should not drive code changes. + +## Build, Test, and Development Commands +Create the environment and install dependencies with `python -m venv .venv` and `.venv/bin/pip install -r requirements.txt`. +Run the app locally with `.venv/bin/uvicorn main:app --reload`. +Use `.venv/bin/python -m py_compile main.py database.py models.py routers/*.py services/*.py` for a fast syntax check before opening a PR. +If you need a clean dependency install, prefer `.venv/bin/pip install -r requirements.txt` over global Python packages. + +## Coding Style & Naming Conventions +Use 4-space indentation and keep Python code straightforward and type-friendly. Follow existing naming: `snake_case` for functions, variables, and module names; `PascalCase` for SQLAlchemy models; uppercase for constants such as shelf metadata. Keep route logic in `routers/` and shared external-service behavior in `services/` rather than duplicating API code across handlers. Jinja templates should stay minimal and defer behavior to `static/app.js` when client-side scripting is needed. + +## Testing Guidelines +There is no committed `tests/` package yet, so add targeted tests alongside any non-trivial feature work. Use `pytest` if you introduce automated tests, with filenames like `test_imports.py` and test names such as `test_watchlist_import_sets_queue_shelf`. For now, every change should at least pass the `py_compile` check and a local smoke test of the affected route in the browser. + +## Commit & Pull Request Guidelines +Git history is not readable from this workspace, so use short imperative commit subjects such as `Add queue watchlist import`. Keep commits focused on one behavior change. Pull requests should explain the user-facing change, note any schema or import implications, list verification steps, and include screenshots for template or CSS updates. + +## Security & Configuration +Keep secrets in `.env`, especially `TMDB_API_KEY`, and never hardcode credentials in Python, templates, or JavaScript. Treat `lumiere.db` and backup database files as local artifacts unless a task explicitly requires fixture data. |