Files
jfmcarreira 66b72d1348
App checks / changes (push) Canceled after 0s
App checks / tournament (push) Canceled after 0s
App checks / shifts (push) Canceled after 0s
feat: monorepo migration phase 5
2026-10-07 15:20:27 +01:00

80 lines
5.0 KiB
Markdown

# 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.
From the monorepo root, `make shifts-dev` prepares the backend's default `data/`
directory and runs Uvicorn on `127.0.0.1:8000` through uv, with auto-reload.
Dependencies resolve through the root `uv.lock` into the root `.venv`. Settings
come from the environment and `backend/.env`; migrations and initial seeding run
on startup, as they do in production.
## Layers
- `backend/app/models/`: persistence schema split into user, team, schedule
(including patterns/rotation members), assignment, swap and notification
modules. The package exports the established model names and registers all
classes with the existing app-specific `Base`; mappings and relationships are
preserved.
- `migrations/`: one Alembic revision, `0001_initial`, holding the whole schema (the history was squashed for a test environment). The app upgrades to `head` on start, and an existing database is adopted by stamping `head`; a database created before Alembic existed has no stamp and is adopted at the baseline.
- `backend/app/services/`: bootstrap, deterministic scheduling, calendar feeds,
SMTP notifications and PDF rendering.
- `backend/app/routers/`: auth, account, calendar, exports, dashboard and swaps.
`admin/` splits teams, users, schedules, assignments and notification-log pages.
Each domain owns its routes; the package composes their routers for `main.py`.
- `routers/dependencies.py`: session/current-user/admin checks, CSRF validation,
flash/context, redirect and month-navigation helpers. Schedule, swap, assignment
and user helper modules support the domains that actually share them. They do
not import feature routers, keeping the dependency graph acyclic.
- `backend/app/security/`: the existing PBKDF2 password codec and CSRF-token
generator. HTTP/session orchestration stays in routers.
- `services/notifications.py`: synchronous SMTP adapter + durable send log.
- `services/pdf.py`: ReportLab-rendered A4 schedule lists, with embedded Unicode fonts and
adaptive layout to keep the selected range on one page.
- `backend/app/cli.py`: maintenance commands that can be run manually or by cron.
- `packages/crr-python`: shared synchronous engine/threading and Alembic-config
construction. Each app supplies its own database setting, script location and
migration policy; the package contains no models or authentication code.
## Data lifecycle
1. Visiting a month calls `ensure_month_assignments`.
2. Missing Night rows use the repeating monthly pattern, or remain unassigned for unconfigured days.
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
`apps/shifts/Dockerfile` uses a repository-root build context, Python 3.13 and uv,
and copies the shared brand package beside the backend. It serves `app.main:app`
on port 8000. Root `compose.yaml` loads `apps/shifts/backend/.env` and mounts the
independent `shifts-data` volume at `/data`, with its database URL pointing to
`/data/bar_rota.db`; default backups live beside it. Run
`docker compose up --build shifts` from the monorepo root. See
[the application README](../README.md) for environment and CLI commands.
Maintenance commands are provided by `python -m app.cli`: `init-db`, `migrate`, `seed-demo`, `db-shell`, and `send-reminders`. Settings come from environment variables and `.env` through `app/config.py`.
`alembic.ini` supplies migration paths and logging configuration. The actual database URL comes from application settings, configured programmatically in `app/database.py` and reused by `migrations/env.py`.
For larger installations, the SQLAlchemy configuration can point to PostgreSQL, but the project intentionally ships only the SQLite deployment path today.
## Testing
Run `make shifts-test` from the monorepo root. It uses the locked uv project to
run pytest and the structural/workflow compatibility verifier. HTTPX supports
FastAPI `TestClient`; pypdf verifies downloaded documents. Fixtures configure
temporary SQLite storage before importing app modules, disable SMTP, run the
existing migration and clean up afterwards. The compatibility verifier copies
a populated synthetic SQLite fixture, checks startup preservation, and compares
schema/ORM/relationships/OpenAPI plus 96 HTTP requests across `/` and `/crr`
against the pre-refactor baseline. Runtime-only randomness/timestamps are
normalized, and calendar clocks are fixed for reproducible comparisons. Raw
comparison results are under ignored `.migration/phase4-results/`; verified
evidence is under `migration/phase4/` and `migration/phase5/`. Phase 5 records the
exact `alembic_config` helper delegation by old/new AST hashes while retaining
the original Phase 4 baseline and guarding the other definitions.