App checks / changes (push) Canceled after 0s
App checks / tournament (push) Canceled after 0s
App checks / shifts (push) Canceled after 0s
80 lines
5.0 KiB
Markdown
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.
|