Merge branch 'docs/architecture-adrs' into develop

docs/adr/0001-use-django-monolith.md

@@ -0,0 +1,35 @@
+# ADR-0001: Use Django Monolith
+
+Date: 2026-04-28
+
+## Status
+
+Accepted
+
+## Context
+
+AzioneLab needs a public theatre company website, a simple booking system, administration tools, email confirmation, QR code generation, and entrance check-in.
+
+The project is small enough that separate backend services would add operational cost without clear benefit. The selected backend stack is Python, Django 5.2 LTS, Django REST Framework, PostgreSQL, and gunicorn.
+
+## Decision
+
+Use a single Django monolith for the backend.
+
+The Django application will own:
+
+- public REST APIs;
+- booking and confirmation logic;
+- QR code generation;
+- check-in validation;
+- Django admin for internal management;
+- database transactions for capacity enforcement.
+
+The Angular frontend remains a separate client application served through nginx.
+
+## Consequences
+
+- The system stays simple to develop, deploy, and operate.
+- Django admin can cover the initial administration needs without building custom admin screens immediately.
+- Booking and capacity rules can be enforced close to the data model.
+- The monolith may need to be split later if traffic, team size, or operational needs grow.

docs/adr/0002-no-async-task-queue.md

@@ -0,0 +1,26 @@
+# ADR-0002: Do Not Add an Async Task Queue Yet
+
+Date: 2026-04-28
+
+## Status
+
+Accepted
+
+## Context
+
+The initial booking flow requires email delivery and QR code generation. These operations are important, but the project does not yet require high-volume background processing, scheduled jobs, retries across many task types, or distributed workers.
+
+Adding Celery, Redis, or another queue would increase deployment and operational complexity for a small theatre company website.
+
+## Decision
+
+Do not use Celery, Redis, or any asynchronous task queue at this stage.
+
+The backend will perform initial email sending and QR code generation synchronously within the Django application, with clear error handling and logging that avoids sensitive data.
+
+## Consequences
+
+- The deployment remains small: Django, PostgreSQL, Angular static assets, and nginx.
+- Local development and production operations are easier to understand.
+- Email provider latency or outages can affect booking and confirmation responses.
+- If email volume, retry needs, or long-running work become a real problem, the project can introduce a task queue later with a new ADR.

docs/adr/0003-qr-code-token-strategy.md

@@ -0,0 +1,26 @@
+# ADR-0003: Use Opaque Tokens in QR Codes
+
+Date: 2026-04-28
+
+## Status
+
+Accepted
+
+## Context
+
+Confirmed reservations need QR codes that visitors can show on a smartphone or printed page. Staff must be able to scan the QR code at the entrance and verify the reservation.
+
+QR codes are easy to copy or share, so they must not expose personal data or encode reservation details directly.
+
+## Decision
+
+QR codes will contain only an opaque, random, non-guessable token or a verification URL containing that token.
+
+The backend will resolve the token server-side, validate that the reservation is confirmed, and reject duplicate check-ins. Tokens must not contain names, email addresses, phone numbers, notes, or other personal data.
+
+## Consequences
+
+- QR codes remain privacy-preserving even if printed, forwarded, or photographed.
+- Token validation stays centralized in the backend.
+- Check-in requires backend availability at the venue.
+- Duplicate check-in prevention depends on reliable server-side state and database constraints.

docs/adr/0004-email-confirmation-flow.md

@@ -0,0 +1,27 @@
+# ADR-0004: Use Email Confirmation for Reservations
+
+Date: 2026-04-28
+
+## Status
+
+Accepted
+
+## Context
+
+Public visitors can request seats for a specific performance. The system needs a simple way to verify that the requester controls the provided email address before issuing a confirmed reservation and QR code.
+
+The system also needs to avoid overbooking when multiple pending reservations exist for the same performance.
+
+## Decision
+
+Create reservations as `pending` first, then send an email confirmation link containing an opaque confirmation token.
+
+A reservation becomes `confirmed` only when the confirmation link is opened and the backend validates the token. Final capacity validation happens during confirmation inside a database transaction. A QR code is generated only after successful confirmation.
+
+## Consequences
+
+- Visitors receive a clear confirmation step before the reservation is finalized.
+- Mistyped or unreachable email addresses are less likely to consume capacity.
+- Pending reservations do not guarantee seats.
+- A visitor may lose availability if other reservations are confirmed before they open the confirmation link.
+- The booking flow depends on email delivery working reliably enough for the audience.