Files
crr-shifts/docs/ARCHITECTURE.md
T

1.4 KiB

Architecture

Runtime

Single FastAPI process with server-rendered HTML and a SQLite database volume. This keeps deployment suitable for a small VPS, NAS or home server.

Layers

  • models.py: persistence schema.
  • scheduling.py: deterministic month/rotation generation.
  • web.py: authentication, admin editing and change-request orchestration.
  • notifications.py: synchronous SMTP adapter + durable send log.
  • cli.py: maintenance commands that can be run manually or by cron.

Data lifecycle

  1. Visiting a month calls ensure_month_assignments.
  2. Missing Night rows are created unassigned.
  3. Missing lunch rows are created from each independent rotation.
  4. Admin assigns/overrides rows on each schedule's own configuration page (the night pattern, or a lunch month view).
  5. Member change requests operate on concrete assignment IDs.
  6. Email is attempted after the database action commits.

Deployment

docker-compose.yml mounts ./data at /app/data, so the SQLite DB persists across image rebuilds. It is the service stack only. docker-compose.dev.yml is the development stack: it builds the dev image target, bind-mounts app/ and tests/ for auto-reload, and hosts the containerized test runner.

For larger installations, the SQLAlchemy configuration can point to PostgreSQL, but the project intentionally ships only the SQLite deployment path today.