5.8 KiB
Architecture
AzioneLab is a public website for a theatre company with a small booking system for performances.
The architecture is intentionally simple: one Django backend, one Angular frontend, one PostgreSQL database, and nginx as the public reverse proxy. There is no Celery, Redis, message broker, or separate worker service at this stage.
Components
Public frontend
The public frontend is an Angular application using Angular Material.
Responsibilities:
- render descriptive pages for the theatre company;
- render the public list of shows;
- render public show and performance detail pages;
- provide the booking form for a selected performance;
- show reservation submission, confirmation, and check-in feedback states;
- call the backend through REST APIs.
The frontend must not calculate authoritative availability. It may display availability returned by the backend, but the backend remains responsible for final capacity validation.
Backend API
The backend is a Django 5.2 LTS application using Django REST Framework.
Responsibilities:
- expose public read APIs for shows, venues, and performances;
- expose public booking and reservation confirmation APIs;
- expose an authenticated check-in verification API;
- provide Django admin or an equivalent authenticated administration area;
- store reservations, tokens, and check-in state;
- calculate performance availability server-side;
- send reservation confirmation emails;
- generate QR codes after reservation confirmation.
The backend runs with gunicorn in production.
Administration area
The first administration area should use Django admin unless a custom Angular admin becomes necessary later.
Administrators can manage:
- shows;
- venues;
- performances;
- total room capacity;
- manually occupied seats;
- optional additional seats available during booking;
- reservation status and check-in records when operationally necessary.
Admin functionality must require authenticated staff access.
Database
PostgreSQL is the system of record.
It stores:
- show and venue content;
- performance scheduling and capacity configuration;
- reservations and explicit reservation status;
- reservation tokens used for confirmation and QR verification;
- check-in records.
Capacity checks must happen inside database transactions to avoid overbooking when multiple users book at the same time.
The backend sends transactional emails for:
- reservation confirmation link after booking submission;
- optional confirmation success email containing the QR code or QR verification link.
Email delivery can use Django's email backend configuration. No asynchronous email worker is required initially; failures should be logged without exposing tokens or personal data.
QR code generation
The backend generates QR codes using a small Python library such as qrcode or segno.
QR codes must contain only an opaque token or verification URL. They must not contain names, email addresses, phone numbers, notes, or other personal data.
nginx
nginx is the public entry point.
Responsibilities:
- terminate HTTP traffic, and TLS when configured;
- serve the built Angular static assets;
- reverse proxy API and admin requests to gunicorn;
- serve static and media files according to the deployment configuration.
Runtime Dependencies
Required runtime dependencies:
- Python;
- Django 5.2 LTS;
- Django REST Framework;
- gunicorn;
- PostgreSQL;
- Angular;
- Angular Material;
- nginx;
- Docker Compose;
- a Python QR code library such as
qrcodeorsegno; - an SMTP-compatible email provider or relay.
Not included at this stage:
- Celery;
- Redis;
- background workers;
- separate search, cache, or queue services.
Data Flow
- A visitor opens the website through nginx.
- nginx serves the Angular frontend.
- The frontend calls public backend API endpoints for shows and performances.
- The visitor submits a booking form for a specific performance.
- The backend validates input, checks capacity server-side, creates a pending reservation, creates a confirmation token, and sends a confirmation email.
- The visitor opens the confirmation link.
- The backend validates the token, confirms the reservation if capacity is still available, and generates a QR code token or QR code image.
- The visitor presents the QR code at the venue using a smartphone or printed copy.
- Staff scans the QR code.
- The backend validates the token and records a check-in if the reservation is confirmed and not already checked in.
Deployment Topology
The initial deployment uses Docker Compose with these services:
nginx: public reverse proxy and static frontend server;frontend: Angular build stage or static asset build source;backend: Django application served by gunicorn;postgres: PostgreSQL database.
Only nginx should be publicly exposed. The backend and database should be reachable only on the internal Compose network.
The initial Compose files live under infra/docker/. The backend and frontend images are placeholders until the Django and Angular applications are implemented.
Architectural Constraints
- Keep the booking workflow synchronous and explicit.
- Keep all capacity validation on the backend.
- Store reservation status explicitly.
- Use opaque, random, non-guessable tokens.
- Do not place personal data in QR codes.
- Avoid optional infrastructure until the project needs it.
- Prefer Django admin for internal management before building custom admin UI.