From db69e242117bbfdc0666d215f010d3cc3b0cd817 Mon Sep 17 00:00:00 2001 From: bisco Date: Tue, 28 Apr 2026 11:34:33 +0200 Subject: [PATCH] chore: update Codex project configuration --- .codex/project.md | 205 +++++++++++++++++++++++++++++++++------------- 1 file changed, 149 insertions(+), 56 deletions(-) diff --git a/.codex/project.md b/.codex/project.md index ee16d0c..9fd31d6 100644 --- a/.codex/project.md +++ b/.codex/project.md @@ -1,31 +1,115 @@ -# Project configuration for Codex - -Edit this file for each repository. +# AzioneLab project configuration for Codex ## Project identity -Project name: `CHANGE_ME` -Project description: `CHANGE_ME` -Primary language/runtime: `CHANGE_ME` +Project name: `AzioneLab` + +Project description: public website for a theatre company with a simple booking system for performances, email confirmation, QR code generation, and staff entrance check-in. + +Primary language/runtime: Python with Django 5.2 LTS. ## Project mode -Choose one: - ```text project_mode: personal -project_mode: work ``` -Rules: +Docker base image policy is neutral, but images must use explicit tags and must not use `latest`. -- `personal`: Docker base image policy is neutral. -- `work`: prefer Red Hat UBI minimal images when possible. +## Tech stack + +- Backend: Python, Django 5.2 LTS, Django REST Framework. +- Backend runtime: gunicorn. +- Frontend: Angular with Angular Material. +- Database: PostgreSQL. +- Reverse proxy: nginx. +- Deployment: Docker Compose. +- QR codes: a small Python QR code library such as `qrcode` or `segno`. +- Email: Django email backend configured through environment variables. + +Do not add Celery, Redis, message brokers, background workers, or extra services unless a future ADR explicitly changes this decision. + +## Architecture + +AzioneLab uses a pragmatic monolith-oriented architecture: + +- a Django backend owns APIs, admin, booking, confirmation, QR generation, check-in validation, and transactional capacity rules; +- an Angular frontend renders public pages, show listings, booking forms, confirmation states, and staff check-in UI; +- PostgreSQL is the system of record; +- nginx is the public reverse proxy and serves frontend assets; +- Docker Compose defines the initial deployment topology. + +Only nginx should be exposed publicly in production. Backend, frontend, and PostgreSQL services should remain on the internal Compose network. + +## Key features + +- Public descriptive pages for the theatre company. +- Public show list and show detail pages. +- Public booking form for a specific performance. +- Administration through Django admin. +- Configurable shows, venues, performance dates, room capacity, manually occupied seats, and optional additional seats. +- Email confirmation before a reservation becomes confirmed. +- QR code generation after reservation confirmation. +- QR codes usable on smartphones or printed copies. +- Staff/admin check-in flow using a mobile-friendly page to scan or enter QR tokens. +- QR verification preview and check-in confirmation endpoints. +- Duplicate check-in prevention. + +## Domain and business constraints + +- A `Performance` belongs to one `Show` and one `Venue`. +- Available seats are calculated server-side as: + +```text +room capacity + additional seats - manually occupied seats - confirmed reservations +``` + +- Reservations start as `pending`. +- Reservations become `confirmed` only through a valid confirmation link. +- Confirmed reservations receive a QR code. +- QR codes must contain only an opaque verification token or URL, never personal data. +- Staff/admin users perform check-in. +- A reservation must be confirmed before check-in. +- A reservation cannot be checked in twice. +- Capacity validation must happen server-side and must avoid overbooking. +- Store reservation status explicitly. +- Public booking endpoints must validate input strictly. +- Admin functionality must require authentication. + +## Security constraints + +- Do not commit secrets, credentials, private keys, raw tokens, or real personal data. +- Use opaque, random, non-guessable tokens for confirmation and QR verification. +- Do not expose personal data in QR codes. +- Do not log raw tokens, credentials, session cookies, authorization headers, or full booking payloads. +- CORS must allow only configured Angular frontend origins through `CORS_ALLOWED_ORIGINS`. +- Keep `.env` files out of version control; `.env.example` may contain example values only. +- Prefer least privilege for containers, users, networks, and filesystem access. + +## Development rules + +Codex MUST: + +- work only on the current feature branch; +- not merge into `develop`; +- keep changes minimal, focused, and easy to review; +- preserve existing architecture decisions unless the user explicitly requests a change; +- update documentation when behavior, deployment, operation, security, or architecture changes; +- create or update ADRs for architectural decisions; +- use Conventional Commits; +- run the configured Docker-based checks before committing; +- report tests/checks, residual risks, and rollback notes. + +Codex MUST NOT: + +- add Celery or Redis; +- add unnecessary services or dependencies; +- implement unrelated features while handling a focused task; +- introduce broad rewrites or formatting-only churn; +- disable authentication, authorization, CSRF, CORS restrictions, TLS verification, input validation, or security checks without an explicit ADR. ## Enabled profiles -Enable only the profiles that apply to this repository: - ```text enabled_profiles: - docker @@ -35,74 +119,83 @@ enabled_profiles: ## Branching model -Codex MUST: +Work must happen on the current feature branch for the task. -- start from `develop`; -- create one branch per task; -- use one of these prefixes: - - `feature/` - - `fix/` - - `hotfix/` - - `chore/` - - `docs/` - - `refactor/` +Allowed branch prefixes when a new branch is explicitly needed: -Examples: +- `feature/` +- `fix/` +- `hotfix/` +- `chore/` +- `docs/` +- `refactor/` -```text -feature/add-healthcheck -fix/selinux-authorized-keys -hotfix/restore-container-startup -``` +Do not merge task branches into `develop`. Leave integration to the repository owner or a separate explicit request. ## Commit style -Codex MUST use Conventional Commits. +Use Conventional Commits. Examples: ```text -feat: add Docker healthcheck -fix: correct Ansible SELinux handling -docs: add ADR for deployment strategy -test: add regression tests for parser -refactor: simplify container startup logic -chore: update Codex project metadata +feat: add health endpoint +fix: correct backend Docker workdir +docs: update deployment notes +test: add reservation capacity checks +refactor: simplify booking token validation +chore: update Codex project configuration ``` -## Test command +## Testing approach -All tests MUST be executed inside Docker containers. +All checks must run inside Docker containers when applicable. -Configure the canonical test command for this repository: +Canonical check command: ```bash docker compose --env-file .env.example -f infra/docker/compose.yml config docker compose --env-file .env.example -f infra/docker/compose.yml run --rm --build backend python manage.py test ``` -Examples: +Current coverage: -```bash -docker compose run --rm app pytest -``` +- Docker Compose configuration validation; +- Django backend tests, including the health endpoint test. -```bash -docker compose run --rm app ruff check . -docker compose run --rm app pytest -``` +Run formatting or linting only when a project configuration for those tools exists. -```bash -docker compose run --rm ansible ansible-playbook --syntax-check playbook.yml -``` +## Deployment approach -If no test command is configured, Codex MUST: +Deployment uses `infra/docker/compose.yml` with explicit services: -1. report that tests are not configured; -2. suggest the appropriate Docker-based test command; -3. avoid claiming that the task is fully verified. +- `nginx`: public reverse proxy; +- `frontend`: Angular frontend build/static service served by nginx; +- `backend`: Django application served by gunicorn; +- `postgres`: PostgreSQL with named volume persistence. -## Documentation language +Configuration comes from `.env`. `.env.example` documents the required environment variables with example values. PostgreSQL data is persisted in the `postgres_data` named volume. + +## Documentation and ADRs + +Primary documentation: + +- `docs/architecture.md` +- `docs/domain-model.md` +- `docs/api-contract.md` +- `docs/booking-flow.md` +- `docs/security-notes.md` +- `docs/deployment.md` +- `docs/testing.md` + +Accepted ADRs currently define: + +- Django monolith backend; +- no async task queue at this stage; +- opaque QR token strategy; +- email confirmation flow; +- staff check-in with token validation; +- Docker Compose deployment. Documentation language: English. Code comments language: English.