generated from bisco/codex-bootstrap
202 lines
6.7 KiB
Markdown
202 lines
6.7 KiB
Markdown
# AzioneLab project configuration for Codex
|
|
|
|
## Project identity
|
|
|
|
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
|
|
|
|
```text
|
|
project_mode: personal
|
|
```
|
|
|
|
Docker base image policy is neutral, but images must use explicit tags and must not use `latest`.
|
|
|
|
## 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
|
|
|
|
```text
|
|
enabled_profiles:
|
|
- docker
|
|
- ansible
|
|
- python
|
|
```
|
|
|
|
## Branching model
|
|
|
|
Work must happen on the current feature branch for the task.
|
|
|
|
Allowed branch prefixes when a new branch is explicitly needed:
|
|
|
|
- `feature/`
|
|
- `fix/`
|
|
- `hotfix/`
|
|
- `chore/`
|
|
- `docs/`
|
|
- `refactor/`
|
|
|
|
Do not merge task branches into `develop`. Leave integration to the repository owner or a separate explicit request.
|
|
|
|
## Commit style
|
|
|
|
Use Conventional Commits.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
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
|
|
```
|
|
|
|
## Testing approach
|
|
|
|
All checks must run inside Docker containers when applicable.
|
|
|
|
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
|
|
```
|
|
|
|
Current coverage:
|
|
|
|
- Docker Compose configuration validation;
|
|
- Django backend tests, including the health endpoint test.
|
|
|
|
Run formatting or linting only when a project configuration for those tools exists.
|
|
|
|
## Deployment approach
|
|
|
|
Deployment uses `infra/docker/compose.yml` with explicit services:
|
|
|
|
- `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.
|
|
|
|
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.
|