generated from bisco/codex-bootstrap
chore: update Codex project configuration
This commit is contained in:
@@ -1,31 +1,115 @@
|
|||||||
# Project configuration for Codex
|
# AzioneLab project configuration for Codex
|
||||||
|
|
||||||
Edit this file for each repository.
|
|
||||||
|
|
||||||
## Project identity
|
## Project identity
|
||||||
|
|
||||||
Project name: `CHANGE_ME`
|
Project name: `AzioneLab`
|
||||||
Project description: `CHANGE_ME`
|
|
||||||
Primary language/runtime: `CHANGE_ME`
|
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
|
||||||
|
|
||||||
Choose one:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
project_mode: personal
|
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.
|
## Tech stack
|
||||||
- `work`: prefer Red Hat UBI minimal images when possible.
|
|
||||||
|
- 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
|
## Enabled profiles
|
||||||
|
|
||||||
Enable only the profiles that apply to this repository:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
enabled_profiles:
|
enabled_profiles:
|
||||||
- docker
|
- docker
|
||||||
@@ -35,74 +119,83 @@ enabled_profiles:
|
|||||||
|
|
||||||
## Branching model
|
## Branching model
|
||||||
|
|
||||||
Codex MUST:
|
Work must happen on the current feature branch for the task.
|
||||||
|
|
||||||
- start from `develop`;
|
Allowed branch prefixes when a new branch is explicitly needed:
|
||||||
- create one branch per task;
|
|
||||||
- use one of these prefixes:
|
|
||||||
- `feature/`
|
|
||||||
- `fix/`
|
|
||||||
- `hotfix/`
|
|
||||||
- `chore/`
|
|
||||||
- `docs/`
|
|
||||||
- `refactor/`
|
|
||||||
|
|
||||||
Examples:
|
- `feature/`
|
||||||
|
- `fix/`
|
||||||
|
- `hotfix/`
|
||||||
|
- `chore/`
|
||||||
|
- `docs/`
|
||||||
|
- `refactor/`
|
||||||
|
|
||||||
```text
|
Do not merge task branches into `develop`. Leave integration to the repository owner or a separate explicit request.
|
||||||
feature/add-healthcheck
|
|
||||||
fix/selinux-authorized-keys
|
|
||||||
hotfix/restore-container-startup
|
|
||||||
```
|
|
||||||
|
|
||||||
## Commit style
|
## Commit style
|
||||||
|
|
||||||
Codex MUST use Conventional Commits.
|
Use Conventional Commits.
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
feat: add Docker healthcheck
|
feat: add health endpoint
|
||||||
fix: correct Ansible SELinux handling
|
fix: correct backend Docker workdir
|
||||||
docs: add ADR for deployment strategy
|
docs: update deployment notes
|
||||||
test: add regression tests for parser
|
test: add reservation capacity checks
|
||||||
refactor: simplify container startup logic
|
refactor: simplify booking token validation
|
||||||
chore: update Codex project metadata
|
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
|
```bash
|
||||||
docker compose --env-file .env.example -f infra/docker/compose.yml config
|
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
|
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 configuration validation;
|
||||||
docker compose run --rm app pytest
|
- Django backend tests, including the health endpoint test.
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
Run formatting or linting only when a project configuration for those tools exists.
|
||||||
docker compose run --rm app ruff check .
|
|
||||||
docker compose run --rm app pytest
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
## Deployment approach
|
||||||
docker compose run --rm ansible ansible-playbook --syntax-check playbook.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
If no test command is configured, Codex MUST:
|
Deployment uses `infra/docker/compose.yml` with explicit services:
|
||||||
|
|
||||||
1. report that tests are not configured;
|
- `nginx`: public reverse proxy;
|
||||||
2. suggest the appropriate Docker-based test command;
|
- `frontend`: Angular frontend build/static service served by nginx;
|
||||||
3. avoid claiming that the task is fully verified.
|
- `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.
|
Documentation language: English.
|
||||||
Code comments language: English.
|
Code comments language: English.
|
||||||
|
|||||||
Reference in New Issue
Block a user