67 lines
3.9 KiB
Markdown
67 lines
3.9 KiB
Markdown
# AGENTS.md — Meal Tracker
|
|
|
|
## Overview
|
|
|
|
Flask web app for tracking household meal attendance. Users register into households, then mark **yes/no** for lunch & dinner each day. A dashboard shows all members' responses. SQLite backend, Docker deployment behind Caddy reverse proxy.
|
|
|
|
- **Repo:** `https://gitea.ct.cozytren.ch/romane/agentbox-test`
|
|
- **Production:** `https://meals.ct.cozytren.ch`
|
|
- **Auto-deploy:** `watch-for-updates.sh` polls for new commits every 20s, rebuilds via `docker compose`, redeploys. Push-to-deploy in ~1 min.
|
|
|
|
## Files — What Goes Where
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `app.py` | Flask factory (`create_app()`), registers blueprints and i18n |
|
|
| `auth.py` | Auth blueprint: `/login`, `/register`, `/logout`. Session-based. |
|
|
| `meals.py` | Meals blueprint: `/dashboard`, `/respond`, `/history`, `/delete-account`, `/admin/*` |
|
|
| `models.py` | All DB access. SQLite via `sqlite3`. 4 tables: `households`, `users`, `meal_periods`, `responses`. |
|
|
| `i18n.py` | Translation module. `t(key)` helper for en/fr/de. Detects `Accept-Language`, session override via `?lang=`. All user-visible strings flow through `t()`. |
|
|
| `templates/` | Jinja2: `base.html` (nav, lang footer), `login.html`, `register.html`, `dashboard.html` |
|
|
| `static/style.css` | All CSS (no framework) |
|
|
| `tests/` | Pytest suite (47 tests): `conftest.py` sets up in-memory DB per test |
|
|
| `Dockerfile` | Python 3.13-alpine. **Must list every `.py` file in the COPY line.** |
|
|
| `docker-compose.yml` | Single service `meal-tracker` on external `caddy` network, volume `meal-data` at `/data` |
|
|
| `watch-for-updates.sh` | Polls git remote, rebuilds on change. Uses `docker compose` with env vars from `.env`. |
|
|
| `doc/index.md` | Full project documentation |
|
|
| `README.md` | Symlink → `doc/index.md` |
|
|
|
|
## Key Conventions
|
|
|
|
- **Blueprints:** `auth_bp` and `meals_bp` registered in `app.py`. Decorator `@login_required` on protected routes.
|
|
- **Session keys:** `user_id`, `username`, `is_admin`, `household_id`, `household_name`, `lang`.
|
|
- **i18n:** Every user-visible string in templates uses `{{ t('English text') }}`. In Python, `flash(t("message"), "category")`. Translations live in `TRANSLATIONS` dict in `i18n.py`. English string is the key; only non-English translations stored. When adding new user-facing text, add it to `TRANSLATIONS` for fr/de.
|
|
- **DB:** All access through `get_db()` context manager in `models.py`. Returns `sqlite3.Row` objects accessed as dicts. Path via `DB_PATH` env var (defaults to `/data/meals.db` in Docker, `./meals.db` locally).
|
|
- **CSS:** No framework. Variables in `:root`. Use existing utility classes (`.btn`, `.chip`, `.badge`, etc.).
|
|
|
|
## Common Pitfalls
|
|
|
|
1. **Dockerfile COPY must include every `.py` file.** If you add a new Python module, add it to the COPY line. Missing files cause `ModuleNotFoundError` → container crash → 502.
|
|
2. **`meal_type` values are lowercase** (`lunch`, `dinner`) in DB/forms. Templates capitalize them for display: `period.meal_type|capitalize`.
|
|
3. **Past dates are read-only.** The respond route rejects dates before today. Dashboard shows badges instead of buttons for other users' rows.
|
|
4. **`changed_at` logic:** Set only when flipping between `yes` ↔ `no`. First answer and `not_answered` transitions leave it NULL.
|
|
5. **Response status values:** `yes`, `no`, `not_answered` (stored in DB; CSS classes and display strings derived from these).
|
|
|
|
## Running Locally (no Docker)
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
python app.py # or: flask --app 'app:create_app()' run --debug
|
|
pytest tests/ -v
|
|
```
|
|
|
|
## Running with Docker
|
|
|
|
```bash
|
|
docker compose up -d --build # needs caddy network
|
|
# or standalone:
|
|
docker build -t meal-tracker .
|
|
docker run -p 5000:5000 meal-tracker
|
|
```
|
|
|
|
## Adding a New Language
|
|
|
|
1. Add the language code and name to `LANGUAGES` in `i18n.py`.
|
|
2. Add translations for every key in `TRANSLATIONS` (keys are the English strings).
|
|
3. Add the language to the footer loop in `templates/base.html`.
|