azionelab/.codex/project.md

# 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.

## Git Workflow Policy

- `develop` is the integration branch.
- `main` is reserved for stable releases.
- For non-trivial changes, Codex MUST work on a dedicated task branch.
- Allowed task branch prefixes: `feature/`, `fix/`, `docs/`, `chore/`.
- Codex MUST NOT merge into `develop` or `main`.
- Codex may commit only on the current task branch after required checks pass.
- The human operator reviews, merges, pushes, and deletes branches.

Allowed branch prefixes when a new branch is explicitly needed:

- `feature/`
- `fix/`
- `chore/`
- `docs/`

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.