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

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:

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

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:

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:

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.