# Inveetaire — Full Project Understanding

> Prepared after reading all mandatory documentation in the prescribed order:
> AI.md → PROJECT.md → WORKFLOW.md → IMPLEMENTATION_ROADMAP.md → PROMPT_LIBRARY.md → PRD → SAD → DDD (Conceptual & Logical) → PDD → DBP → ADR → MIB → TCS

---

## 1. What is Inveetaire?

**Inveetaire** is a **wedding management platform** built for the Indonesian market. It solves a real operational problem: couples managing a wedding face fragmented tooling — invitation distribution is handled via one WhatsApp link generator, guest tracking via another spreadsheet, and reception desk check-in via a third improvised process. None of these tools talk to each other.

Inveetaire unifies the entire wedding operations lifecycle into **one workspace**:
- Digital invitations (personalized, mobile-first)
- RSVP collection (zero friction for guests)
- Guest management (import, track, communicate)
- Vendor budget tracking
- Wedding day check-in (QR scan, live dashboard)
- Post-event reporting

The product serves **two operational modes**:
1. **Setup Mode** — couple configures their workspace (invitation, guests, vendors)
2. **Execution Mode (Live)** — wedding day check-in, live dashboard, angpao tracking

---

## 2. Product Philosophy

The five core principles, as established in the documentation:

| Principle | Meaning |
|-----------|---------|
| **"Technology supports the event. It never stops it."** | No technical failure should halt wedding day operations. Offline mode for check-in is mandatory. |
| **"One Wedding. One Workspace. Everyone Aligned."** | All roles (couple, crew, super admin) see the same shared operational state. |
| **"Shared operational awareness over individual automation."** | The system helps humans make better decisions; it does not automate away their judgment. |
| **"Guest friction must always be zero."** | Guests never create an account. Their URL is their identity. One link for the entire journey. |
| **"One Guest, One URL, One QR, One Journey."** | The personalized invitation URL serves: viewing, RSVP, reminder, and QR check-in display — forever. |

**Curated quality over flexibility**: Couples personalize content within curated themes — they never design layouts. Every invitation looks professional by design.

---

## 3. Architecture

### Stack (FROZEN)
- **Backend**: Native PHP 7.4
- **Database**: MariaDB / MySQL (PostgreSQL migration-ready)
- **Frontend**: HTML5, TailwindCSS, Alpine.js, FontAwesome
- **Hosting**: Shared hosting (cPanel/Rumahweb — no Redis, no Docker, no background workers)

### Five Surfaces, Nine Engines
**Surfaces (who uses what):**
1. **Super Admin Portal** (`/app/admin/`) — platform management
2. **Couple Portal** (`/app/couple/`) — wedding planning workspace
3. **Crew Portal** (`/app/crew/`) — wedding day check-in only
4. **Guest Surface** (`/{slug}/invite/{guest_code}`) — public, no auth
5. **Support Mode** — Super Admin overlay into couple workspaces (audited)

**Routing**: Single front controller at `public/index.php`. Apache `.htaccess` routes all requests there. Five route namespaces. No PHP file is accessed directly.

### Authentication & Identity
| Actor | Method |
|-------|--------|
| Super Admin | Email + Password → session |
| Couple | Email + Password → session + workspace_id |
| Crew | Username + Password → session + workspace_id |
| Guest | No auth — Guest Code in URL is identity |

### Multi-Tenancy
- **Single shared database**, isolation by `workspace_id` on every tenant table
- `workspace_id` is non-nullable, always included in queries as a bound parameter
- No workspace may access another workspace's data — enforced at application layer

### Workspace Lifecycle States
`Provisioned → Setup → Active → Live → Post-Event → Archived → Purged`

---

## 4. Database Strategy

### Three-Phase Design (All APPROVED & FROZEN)
1. **DDD v1.0 — Conceptual**: 32 business entities, ownership, lifecycle, relationships (no SQL)
2. **DDD v1.1 — Logical**: Attributes, cardinality, constraints, status models, naming rules (no types)
3. **PDD v1.0 — Physical**: 35 MySQL/MariaDB tables, column types, indexes, foreign keys, seed data

### 35 Tables (Migration order documented)
Organized into 7 groups:
1. **Platform & Identity**: `roles`, `event_types`, `commercial_plans`, `workspaces`, `users`, `sessions`, `support_sessions`, `retention_policies`
2. **Invitation & Theme**: `themes`, `theme_versions`, `theme_event_types`, `invitations`, `invitation_sections`, `wishes`
3. **Guest Management**: `guests`, `guest_events`, `rsvps`, `guest_timelines`
4. **Wedding Day Operations**: `wedding_events`, `checkins`, `label_print_jobs`, `crew_accounts`
5. **Vendor & Budget**: `vendors`, `vendor_payments`
6. **Communication**: `message_templates`, `communication_logs`
7. **Files, Config & Audit**: `media_files`, `media_variants`, `system_configurations`, `workspace_configurations`, `printer_configurations`, `notifications`, `audit_logs`

### Key Database Rules
- **Parameterized PDO** — no string-concatenated SQL, ever
- **No `SELECT *`** — only named columns
- **Soft delete** for: Guest, Vendor, Vendor Payment, Wedding Event, Crew Account, Wish
- **Immutable append-only**: Audit Log, Guest Timeline, Check-in, Communication Log
- **Hard delete**: Media Files, Media Variants, Sessions, Notifications
- **`audit_logs`**: INSERT only — UPDATE and DELETE revoked at DB user level
- All timestamps in UTC; `DATETIME` (not `TIMESTAMP`) for PostgreSQL migration readiness
- **Status fields**: `VARCHAR` (not `ENUM`) for PostgreSQL compatibility
- **Money**: `DECIMAL(15,2)` — no floats
- Guest Code: 16-char cryptographically random alphanumeric, unique per workspace

### Key Indexes
- `uq_workspaces_slug` — globally unique slug
- `uq_guests_code_workspace` — guest code unique per workspace
- `idx_guests_workspace_id`, `idx_guests_rsvp_status`, `idx_guests_checkin_status` — dashboard aggregations
- `idx_checkins_workspace_event` — live wedding day dashboard polling

### Seed Data at Deployment
- 3 Roles: Super Admin, Couple, Event Crew
- 2 Event Types: Wedding, Engagement
- 2 Commercial Plans: Starter (500 guests, 3 crew), Professional (1000 guests, 10 crew)
- 1 Default Theme: "Klasik Putih" v1.0
- 12 System Configuration keys (session timeouts, file limits, guest code length, etc.)

---

## 5. Modular Architecture

### 17 Modules (FROZEN — no new modules without an ADR)
Located at `app/modules/{ModuleName}/`

| Module | Responsibility |
|--------|---------------|
| **Auth** | Login, logout, session, password reset for all 3 user types |
| **Workspace** | Provisioning, setup checklist, lifecycle phase transitions |
| **Invitation** | Theme config, couple content, section visibility, public invitation rendering |
| **Guest** | Guest CRUD, Excel import/export, QR codes, status tracking |
| **RSVP** | RSVP form processing, PAX validation, window enforcement |
| **Checkin** | QR scan, manual search, PAX/angpao recording, offline queue, duplicate detection |
| **Dashboard** | Aggregates from Guest + Vendor + Notification; live wedding day dashboard |
| **Vendor** | Vendor CRUD, payment milestones, budget aggregation |
| **Communication** | Message template management, WhatsApp pre-fill links, comm logs |
| **Theme** | Manifest loading, version resolution, rendering context assembly |
| **Media** | File upload validation, variant generation, secure serving, deletion |
| **Audit** | Audit log writes (called by all modules), reads for Admin/Couple |
| **Notification** | Condition evaluation, badge count, expiry |
| **Printer** | Label template config, post-check-in label generation, print acknowledgement |
| **Report** | Post-event report generation, Excel/CSV export |
| **Settings** | System config (Admin), workspace config (Couple), crew accounts, printer config |
| **Support** | Support Mode session lifecycle, workspace context adoption |

### Each Module Contains
```
app/modules/{Module}/
├── {Module}Controller.php   # HTTP handling only — max 20 lines per method
├── {Module}Service.php      # All business logic
├── {Module}Model.php        # All database access (parameterized PDO only)
├── {Module}Validator.php    # Input validation (shape/format, not business rules)
├── {Module}Config.php       # Module-specific constants
├── routes.php               # Route definitions for this module
└── views/                   # PHP view files — no DB calls, no service calls
```

### Iron Rules
- **No cross-module direct DB access** — Module A calls Module B's Service, never its Model
- **Thin Controllers** — receive, validate, delegate, respond. Max 20 lines.
- **Fat Services** — all business rules, status transitions, audit log writes
- **Models only do queries** — no business logic, always scoped with `workspace_id`
- **Views only display** — receive fully-prepared data, all output escaped

---

## 6. Implementation Roadmap

The IMPLEMENTATION_ROADMAP.md defines sprints as "Epics" with atomic user stories (tickets). The MIB (Master Implementation Blueprint) / TCS (Ticket Catalog Specification) defines the actual tickets.

### Sprint Sequence (Epics)

| Epic | Name | Purpose |
|------|------|---------|
| **Epic 0** | Project Initialization | Folder structure, environment, bootstrap, router, middleware, session, DB connection, error handler |
| **Epic 1** | Core Utilities | Response helpers, validation engine, pagination, search/sort, UI components, date/string helpers |
| **Epic 2** | Authentication | Login/logout for all 3 roles, session management, timeout, password reset |
| **Epic 3** | Workspace | Provisioning, setup checklist, lifecycle phase transitions |
| **Epic 4** | Theme Engine | Theme manifest loader, couple configuration UI, public invitation renderer, media upload |
| **Epic 5** | Guest Management | Guest CRUD, Excel import/export, QR code generation, guest timeline, wedding events, guest-event assignment |
| **Epic 6** | RSVP | RSVP form, PAX validation, window enforcement, RSVP management for couple |
| **Epic 7** | Communication | Message template management, WhatsApp pre-fill link generation, comm log |
| **Epic 8** | Vendor Management | Vendor CRUD, payment milestones, budget tracking, high-risk detection |
| **Epic 9** | Wedding Day Check-in | QR scan, manual check-in, offline queue, live dashboard, label printing |
| **Epic 10** | Couple Dashboard | Aggregated planning dashboard, notifications |
| **Epic 11** | Reporting | Post-event reports, exports |
| **Epic 12** | Super Admin | Workspace management, theme catalogue, system config, audit log viewer |
| **Epic 13** | Support Mode | Support Mode entry/exit, auditing, visual banner |
| **Epic 14** | Hardening | Security audit, performance testing, final checklist verification |

---

## 7. Sprints in Order

1. Sprint 0 → **Epic 0: Project Initialization**
2. Sprint 1 → **Epic 1: Core Utilities**
3. Sprint 2 → **Epic 2: Authentication**
4. Sprint 3 → **Epic 3: Workspace**
5. Sprint 4 → **Epic 4: Theme Engine & Invitation**
6. Sprint 5 → **Epic 5: Guest Management**
7. Sprint 6 → **Epic 6: RSVP**
8. Sprint 7 → **Epic 7: Communication**
9. Sprint 8 → **Epic 8: Vendor Management**
10. Sprint 9 → **Epic 9: Wedding Day Check-in**
11. Sprint 10 → **Epic 10: Couple Dashboard**
12. Sprint 11 → **Epic 11: Reporting**
13. Sprint 12 → **Epic 12: Super Admin Portal**
14. Sprint 13 → **Epic 13: Support Mode**
15. Sprint 14 → **Epic 14: Hardening & Security Audit**

---

## 8. Assumptions

1. **XAMPP environment is functional**: Apache, PHP 7.4, MySQL/MariaDB are all running at `c:\xampp\htdocs\inveetaire`.
2. **PHP extensions required**: `pdo_mysql`, `mbstring`, `gd` (for image variants), `zip` (for Excel parsing). These need to be confirmed in `php.ini`.
3. **Excel library**: Since there is no Composer mentioned for MVP, Excel import likely requires a pure-PHP library (e.g., PhpSpreadsheet — but this requires Composer). The DBP mentions "no new libraries without approval" — this needs resolution before GUEST-004.
4. **QR code library**: QR code generation (GUEST-005) requires either a PHP library or an external API. Same Composer dependency question applies.
5. **Email for password reset**: AUTH-003 requires email sending. On shared hosting, PHP `mail()` or an SMTP configuration is needed. No email service is specified in the stack.
6. **No Redis/no queue**: All operations are synchronous. Image variant generation happens inline during upload. This is acceptable at MVP scale but may cause timeout issues on shared hosting with large images.
7. **"Klasik Putih" theme**: The seed data and theme loader reference this theme, but no theme package files exist in `themes/klasik-putih/` yet. This must be created as part of Epic 4.
8. **Database migration scripts**: The PDD documents the schema but no SQL migration files exist yet. Epic 0 must include creating these.
9. **Super Admin account**: The first Super Admin user must be seeded — no provisioning flow exists for the very first user.

---

## 9. Potential Risks

### Technical Risks

| Risk | Severity | Mitigation |
|------|----------|-----------|
| **PHP extension gaps** on shared hosting (GD, zip, PDO) | High | Verify at Epic 0. `phpinfo()` check before any code. |
| **Composer dependency for Excel/QR** — not addressed in stack | High | Decide early: Composer OK or pure-PHP alternative (e.g., PHPExcel-style bundled lib)? Needs explicit ADR. |
| **Image processing timeout** on shared hosting (GD + large files) | Medium | Enforce file size limits strictly (10 MB). Consider async-feeling UX even if sync. |
| **Offline check-in sync** (C8 rule) using browser localStorage | Medium | Alpine.js + localStorage is within stack. Must handle race conditions on sync. |
| **Session storage on shared hosting** — file-based sessions can fail under load | Low-Medium | Configure `session.save_path` in `session.php` to a writable directory. |
| **QR code scanning via webcam** on non-HTTPS localhost | Medium | WebRTC camera API requires HTTPS in production. Shared hosting SSL is needed from day one. |
| **`storage/` directory permissions** on shared hosting | Medium | Document `chmod 755` requirements. Verify `.htaccess` protection works on host. |

### Process Risks

| Risk | Severity | Mitigation |
|------|----------|-----------|
| **Creeping scope** — adding features not in PRD | High | AI.md rules + DBP Chapter 14 are explicit. Every ticket references a PRD section. |
| **Cross-module coupling** — violating module isolation | Medium | Module checklist in DBP Ch.12 prevents this if followed. |
| **Audit log gaps** — forgetting to call AuditService | Medium | Module checklist item #10 is mandatory before a module is considered complete. |
| **Missing CSRF tokens** — especially on AJAX calls | Medium | Security checklist item enforced on every ticket. |
| **Theme manifest mismatch** — theme sections not matching DB `invitation_sections` | Medium | Theme loader validation (THEME-001) catches this — must be strict. |
| **Workspace isolation breach** — a query missing `workspace_id` | Critical | Every model query and every code review checks this. It is item #9 on the module checklist. |

---

## 10. Confirmation

I have read and understood all mandatory documentation in the prescribed order. My understanding of Inveetaire is complete.

**I understand:**
- The product: a wedding management SaaS for the Indonesian market
- The philosophy: zero guest friction, shared operational awareness, technology serves events
- The architecture: native PHP 7.4, modular MVC, single-entry front controller, 5 route namespaces
- The database: 35 tables, workspace_id isolation, parameterized PDO, immutable audit log
- The module system: 17 modules, thin controllers, fat services, no cross-module DB access
- The implementation sequence: 15 Epics in strict dependency order
- The rules: no invented features, no architecture changes, no unescaped output, no string-concatenated SQL

**I am ready to begin Sprint 0 (Epic 0: Project Initialization).**

Sprint 0 will create:
- Complete folder structure per DBP v1.0 Chapter 2
- Environment configuration (`.env`, `.env.example`, config files)
- Front controller (`public/index.php`)
- Apache `.htaccess` rewrite rules
- Config loader and `env()` helper
- Global error handler and logger
- Core router
- Base Controller, Model, Service classes
- Middleware pipeline (Auth, Role, CSRF, Workspace, Guest, Support)
- Session manager, CSRF token system, flash messages
- View renderer and layout system
- Database connection (PDO singleton)

**Awaiting your approval to begin.**