feat: initial implementation

This commit is contained in:
jfmcarreira committed 2026-10-05 22:36:27 +01:00
commit e29da874ee
39 files changed
+2309

No files matched your search

+28
View File
@@ -0,0 +1,28 @@
# 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 through the month editor.
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.
For larger installations, the SQLAlchemy configuration can point to PostgreSQL, but the project intentionally ships only the SQLite deployment path today.
+66
View File
@@ -0,0 +1,66 @@
# Domain model
## Schedules vs assignments
A **schedule** describes when a duty exists and how its initial assignee is chosen. An **assignment** is the actual duty on a concrete date. Once an assignment exists, it is not recalculated from the schedule.
This distinction is intentional: editing a rotation must not retroactively change an already published month.
## Seeded schedules
### Night
- Exists every day (`Monday` through `Sunday`).
- Type: `fixed`.
- Generation creates an unassigned row for every date.
- An administrator assigns a person for each date in **Manage month**.
- Once assigned, it remains fixed until explicitly edited or transferred through an approved change request.
### Saturday Lunch
- Saturdays only.
- Type: `rotation`.
- Has its own ordered member list.
- Uses an anchor date to continue the rotation across month boundaries.
### Sunday Lunch
- Sundays only.
- Type: `rotation`.
- Has its own ordered member list, independent of Saturday.
The data model supports a schedule matching multiple weekdays even though the seeded lunch schedules each use one day.
## Rotation generation
For a rotation schedule, the member is chosen from the ordered active rotation members using the number of matching schedule days from the anchor date to the target date modulo member count.
Only missing assignments are generated. Existing rows are never rewritten.
## Change request state machine
`open` → `pending_approval` → `approved`
Other terminal states: `rejected`, `cancelled`.
- A member can offer one of their future/current assignments to a specific active member or to anyone.
- The requester cannot accept their own request.
- A targeted request can only be accepted/rejected by that target.
- An open request can be accepted by any other active member.
- If the schedule requires manager approval, acceptance moves to `pending_approval`.
- Approval transfers the assignment and sets its source to `swap`.
- If the requester no longer owns the assignment, the request must not be applied.
## Notifications
Email is optional per user and per installation.
Events include:
- assignment updated/removed by admin;
- change requested;
- change accepted;
- manager approval required;
- change approved/rejected;
- shift reminder.
An email error is logged but must not undo a scheduling action.
+15
View File
@@ -0,0 +1,15 @@
# Roadmap / intentionally deferred
Good next additions if the association needs them:
- Alembic migrations before production schema evolution.
- Password self-service and forgot-password flow.
- Phone notifications via an explicit SMS/WhatsApp provider.
- iCalendar (`.ics`) export / personal calendar subscription.
- Holiday/special-event exceptions.
- Optional schedule eligibility groups.
- Audit log for every admin assignment edit.
- PostgreSQL deployment profile and automated backups.
- Localization (Portuguese/English).
Not planned unless specifically requested: payroll, attendance/time clock, HR records, leave accrual, performance management.