# PILOT-002 Architecture Alignment Review — Guest Import Engine

**Reviewer Role:** Principal Software Architect  
**Review Date:** 2026-07-06  
**Pilot Phase:** Pilot Launch (Module Guest)  
**Scope:** GuestController, GuestService, GuestModel, GuestValidator, GuestImporter, routes.php, import.php, import_result.php

---

## 1. Executive Summary

This alignment review evaluates the architectural design and implementation of the **Guest Import Engine (PILOT-002)** against the long-term Pilot Launch roadmap. The primary objective is to verify that the imported guest dataset, token generation parameters, and workspace boundaries serve as a stable foundation for the upcoming public-facing features (Personal Invitation URLs, WhatsApp Share, RSVP, QR Code Check-in, and the Attendance Dashboard).

**Verdict:** The current implementation conforms to the MVC + Service + Model layered architecture, strictly enforces workspace isolation, and generates cryptographically secure identifiers. It is aligned with the roadmap, with minor recommendations for future column refactoring.

---

## 2. Architecture Alignment

The Guest module implements the Zero-Dependency layout philosophy:
* **Controller:** Remains thin, orchestrating HTTP uploads and redirecting via the POST-Redirect-GET pattern.
* **Service:** Coordinates file reading, column mapping, duplication checks, and token generation.
* **Model:** Scopes all queries by `workspace_id`, ensuring no cross-workspace data leakage.
* **Importer:** Integrates a lightweight XLSX zip-XML parser, eliminating external library bloat.

---

## 3. Guest Identity Review

The current implementation utilizes the database column `guest_code` as the unique public identifier.
* **Terminology Alignment:** While the roadmap references a "guest token," mapping the code variable directly to the database column name (`guest_code`) is correct. It avoids terminology drift between schema naming and PHP variable naming.
* **Exposure:** Public URLs (e.g. `/invitation/{guest_code}`) and QR codes will rely on this code. Since the database column has a unique index `uq_guests_code_workspace` scoped to `(workspace_id, guest_code)`, the identifier is isolated.

---

## 4. Guest Data Model Review

To adhere to the "do not modify schema" constraint of the current task, optional attributes (**Category**, **Seat Number**, and **Address**) are stored inside the unstructured `notes` column as text lines:
`Category: Family | Seat Number: Table A`

### Long-Term Impact Analysis:
1. **Seating:** Operates as a text label. Future seating modules cannot query, reserve, or sort seats at database-level without complex, un-indexed text searches.
2. **VIP & Reports:** Cannot group or count analytics by category cleanly.
3. **QR Check-in / Label Printing:** The printing system must parse out `Seat Number` dynamically from the text string at print-time, raising the risk of formatting mismatches.

### Recommendation:
* Storing these fields in `notes` is acceptable for the Pilot Launch validation phase.
* **Backlog Action:** In a future database update sprint, Category, Seat Number, and Address must be promoted to dedicated, nullable columns in the `guests` table to support relational indexes and sorting.

---

## 5. Token Review

The generated token is saved in `guests.guest_code`.
* **Randomness:** Uses cryptographically secure random bytes (`random_bytes(8)`).
* **Length:** 16-character hexadecimal string.
* **Entropy & Collision Resistance:** $16^{16} = 2^{64}$ states. For a maximum of 1,000 guests per workspace, collision probability is virtually zero. A 10-iteration loop collision check guarantees absolute uniqueness.
* **URL Safety:** Hex characters require no encoding and remain highly compact for mobile URLs.
* **Conclusion:** The generated token is highly secure, URL-safe, and fit as the permanent public guest identifier.

---

## 6. Future Compatibility

The Guest module design supports the downstream roadmap:
* **Personal Invitation URL:** The 16-char `guest_code` can be appended directly to the base domain (e.g., `inveetaire.com/inv/a1b2c3d4e5f6g7h8`).
* **WhatsApp Share:** The system can compose template messages mapping the guest code parameters.
* **RSVP & Wishes:** The `guests.id` maps directly to `rsvps.guest_id` and `wishes.guest_id` as foreign keys.
* **QR Check-in:** The check-in script only needs to read the `guest_code` from the scanned URL, locate the guest row, and update `checkin_status = 'checked_in'`. No new columns are required.

---

## 7. Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Parsing Seat/Category from `notes` text during label prints | Medium | Use structured prefix delimiters (e.g. `Category: X | Seat: Y`) and write a helper to parse them safely, or add columns in the next phase. |
| XLSX imports fail if PHP host lacks `ZipArchive` | Low | Added class check to fail gracefully with an explanatory message rather than throwing a fatal error. |

---

## 8. Recommendations

| # | Recommendation | Type | Description |
|---|----------------|------|-------------|
| 1 | Keep `guest_code` as the codebase variable name | **Recommended** | Avoids split-terminology debt since the DB column is `guest_code`. |
| 2 | Refactor Category, Seat, and Address to dedicated columns | **Recommended** | Queue this database schema change for the next platform configuration phase to enable advanced seating and print layouts. |
| 3 | Maintain the 16-character hex token format | **Mandatory** | Proven to be cryptographically secure and URL-safe. |

---

## Ready for Pilot-003

# YES

The Guest Import Engine architecture is sound, safe, and fully aligned with the future roadmap. No changes are required to the codebase before beginning PILOT-003.

---
*End of PILOT-002 Architectural Alignment Review*