docs: add initial architecture documentation

docs/deployment.md

@@ -1,15 +1,167 @@
 # Deployment
 
-Describe how this project is deployed.
+AzioneLab should deploy with a simple Docker Compose topology:
 
-Include:
+- `nginx`: public reverse proxy and static frontend server;
+- `frontend`: Angular build source or build stage for static assets;
+- `backend`: Django 5.2 LTS application served by gunicorn;
+- `db`: PostgreSQL database.
 
-- environments;
-- Docker/Compose usage;
-- required configuration;
-- secrets handling;
-- exposed ports;
-- volumes;
-- networks;
-- deployment commands;
-- rollback procedure.
+Only nginx should expose public ports. The backend and database should stay on the internal Compose network.
+
+## Services
+
+### nginx
+
+Responsibilities:
+
+- listen on public HTTP and HTTPS ports;
+- serve built Angular files;
+- proxy `/api/` and `/admin/` requests to the backend;
+- serve static and media files according to the selected storage layout;
+- apply request size and timeout limits appropriate for booking and admin usage.
+
+Public ports:
+
+- `80` for HTTP;
+- `443` for HTTPS in production.
+
+### frontend
+
+The frontend is an Angular application using Angular Material.
+
+Deployment options:
+
+- build the Angular app in a Docker build stage and copy static files into the nginx image;
+- or run a one-shot build container that writes static files to a shared volume consumed by nginx.
+
+The first option is preferred for a simple production deployment because nginx can serve immutable built assets without a long-running Node process.
+
+### backend
+
+The backend is a Django application served by gunicorn.
+
+Responsibilities:
+
+- REST API;
+- Django admin;
+- booking, confirmation, QR generation, and check-in logic;
+- transactional capacity validation;
+- email sending.
+
+The backend should run database migrations before or during deployment through an explicit operational command, not as hidden startup magic unless that choice is documented later.
+
+### db
+
+PostgreSQL is the only database service.
+
+Responsibilities:
+
+- persistent application data;
+- reservation and check-in state;
+- transactional capacity enforcement.
+
+Use a named Docker volume for database data.
+
+## Networks
+
+Recommended Compose networks:
+
+- `public`: nginx-facing network when needed;
+- `internal`: private network for nginx, backend, and db communication.
+
+The database should not be published to the host in production.
+
+## Volumes
+
+Recommended volumes:
+
+- `postgres_data`: PostgreSQL data directory;
+- `media`: uploaded media and generated QR assets if stored on disk;
+- `static`: collected Django static files if served by nginx from a shared volume.
+
+Generated QR codes may also be generated on demand instead of stored as files. If stored, they must not reveal personal data and access must remain controlled.
+
+## Configuration
+
+Required backend configuration:
+
+- `DJANGO_SECRET_KEY`;
+- `DJANGO_ALLOWED_HOSTS`;
+- `DJANGO_CSRF_TRUSTED_ORIGINS`;
+- `DATABASE_URL` or equivalent database settings;
+- email host, port, username, password, TLS settings, and sender address;
+- public site URL used to build confirmation and QR verification links.
+
+Required database configuration:
+
+- database name;
+- database user;
+- database password;
+- data volume path.
+
+Required nginx configuration:
+
+- upstream backend service name and port;
+- static frontend root;
+- proxy rules for `/api/` and `/admin/`;
+- TLS certificate paths for production.
+
+Secrets must be provided through deployment-managed environment variables, Docker secrets, or another secret manager. Do not commit real secret values.
+
+## Example Request Routing
+
+```text
+Visitor browser
+  -> nginx
+    -> Angular static files
+    -> /api/ requests proxied to backend:gunicorn
+    -> /admin/ requests proxied to backend:gunicorn
+Backend
+  -> PostgreSQL
+  -> SMTP provider
+```
+
+## Deployment Commands
+
+The exact commands will be finalized when application code and Compose files are added.
+
+Expected production-style flow:
+
+```bash
+docker compose build
+docker compose run --rm backend python manage.py migrate
+docker compose run --rm backend python manage.py collectstatic --noinput
+docker compose up -d
+```
+
+Expected validation commands:
+
+```bash
+docker compose config
+docker compose run --rm backend python manage.py check --deploy
+docker compose run --rm backend python manage.py test
+```
+
+The repository does not yet define the canonical Docker-based test command.
+
+## Rollback
+
+Rollback should be designed around immutable images and database backups.
+
+Basic rollback steps:
+
+1. identify the previous known-good image tags or Git commit;
+2. stop the current Compose stack;
+3. deploy the previous image tags or commit;
+4. restore the database from backup only if a migration or data change requires it;
+5. run smoke checks for public pages, booking creation, confirmation, and check-in.
+
+Database rollback needs special care once migrations exist. Down migrations or backup restore procedures should be documented before production use.
+
+## Operational Notes
+
+- Configure database backups before accepting real bookings.
+- Monitor backend errors, email delivery failures, and check-in failures.
+- Keep container images explicitly versioned; do not use `latest` tags.
+- Keep the system small until operational needs justify additional services.