docs: add initial architecture documentation

docs/booking-flow.md

@@ -0,0 +1,136 @@
+# Booking Flow
+
+This document describes the full public booking, confirmation, QR generation, and entrance check-in flow.
+
+## 1. Public Discovery
+
+1. A visitor opens the public website.
+2. The Angular frontend requests published shows and upcoming performances from the backend.
+3. The visitor opens a show detail page.
+4. The frontend displays upcoming public performances and availability returned by the backend.
+
+Availability shown to visitors is informational. The backend recalculates availability when reservation state changes.
+
+## 2. Booking Submission
+
+1. The visitor selects a performance.
+2. The frontend displays the booking form for that performance.
+3. The visitor enters contact details and party size.
+4. The frontend submits the booking request to the backend.
+5. The backend validates:
+   - required fields;
+   - email format;
+   - positive party size;
+   - performance exists and booking is open;
+   - requested seats do not exceed currently available seats.
+6. The backend creates a `pending` reservation.
+7. The backend creates a random opaque confirmation token.
+8. The backend sends an email with a confirmation link.
+9. The frontend tells the visitor to check their email.
+
+The reservation is not confirmed at this stage.
+
+## 3. Email Confirmation
+
+1. The visitor opens the confirmation link from the email.
+2. The frontend or backend submits the confirmation token to the confirmation endpoint.
+3. The backend validates that the token:
+   - exists;
+   - has the `confirmation` purpose;
+   - belongs to a pending reservation;
+   - has not expired;
+   - has not already been used.
+4. The backend starts a database transaction.
+5. The backend locks the related performance row.
+6. The backend recalculates confirmed reservations for the performance.
+7. The backend confirms the reservation only if enough seats remain.
+8. The backend marks the confirmation token as used.
+9. The backend creates a QR verification token.
+10. The backend generates a QR code containing the opaque QR token or a verification URL.
+11. The backend returns or sends the QR code to the visitor.
+
+If there is no longer enough capacity, the backend must not confirm the reservation.
+
+## 4. QR Code Delivery
+
+After confirmation, the visitor receives access to a QR code.
+
+The QR code may be delivered as:
+
+- an image displayed on the confirmation page;
+- an image or link in a confirmation email;
+- a printable page linked from the confirmation result.
+
+The QR code must be usable from a smartphone screen or printed copy.
+
+The QR code must contain:
+
+- an opaque check-in token; or
+- a verification URL containing an opaque token.
+
+The QR code must not contain:
+
+- visitor name;
+- email address;
+- phone number;
+- notes;
+- party size if avoidable;
+- any other personal data.
+
+## 5. Entrance Check-In
+
+1. Staff opens the authenticated check-in interface.
+2. Staff scans the visitor's QR code.
+3. The frontend submits the scanned token to the backend.
+4. The backend validates:
+   - staff authentication and permission;
+   - token exists and has the `check_in` purpose;
+   - reservation exists;
+   - reservation is confirmed;
+   - token is valid for the performance check-in window if such a window is configured;
+   - reservation has not already been checked in.
+5. The backend creates a `CheckIn` record.
+6. The backend returns a successful check-in response.
+7. Staff admits the visitor party.
+
+## Duplicate Check-In
+
+If the same QR code is scanned again:
+
+1. The backend detects an existing check-in for the reservation.
+2. The backend returns `409 Conflict`.
+3. The backend does not create a second check-in.
+
+The response should be clear enough for staff to understand that the reservation was already used.
+
+## Capacity Handling
+
+Capacity is calculated as:
+
+```text
+room capacity + additional seats - manually occupied seats - confirmed reservations
+```
+
+Only confirmed reservations consume capacity. Pending reservations represent interest, not a guaranteed seat.
+
+To avoid overbooking, final confirmation must be transactional:
+
+1. lock the performance;
+2. recalculate confirmed seats;
+3. compare availability with requested party size;
+4. confirm only when seats are available.
+
+## Failure States
+
+Expected failure states include:
+
+- invalid booking input;
+- booking disabled for the performance;
+- no capacity remaining;
+- confirmation token expired;
+- confirmation token already used;
+- QR token invalid;
+- reservation not confirmed;
+- reservation already checked in.
+
+Each failure should return a clear status code and a concise user-facing message.