# Event Sessions — Phase 3 Architecture & UI/UX Design This document specifies the complete functional architecture, UX design, wireframes, and business rules for the Couple Admin **Event Session Management** interface. --- ## 1. Functional Specification ### 1.1 Objective & Scope The Event Session Management feature enables couples to configure multiple invitation schedules (sessions) for any of the 3 core wedding events: 1. **Holy Matrimony** 2. **Tea Pai** 3. **Reception** > **Strict System Constraint**: The application maintains strictly 3 wedding events. No new event types are added. Sessions exist as child schedules under these 3 events. ### 1.2 Capability Matrix | Feature | Single-Session Event | Multi-Session Event | |---|---|---| | Displayed Schedule | Base Event Date / Time | Session Start Time (Guest-Specific) | | Session Management | Read-only Default Session Card | Add / Edit / Delete / Sort Sessions | | Guest Assignment | Auto-assigned Default Session | Select specific session via Dropdown | | Venue Override | Inherits main event venue | Custom venue/room override per session | | Default Session | Auto-generated (`is_default = 1`) | One session designated as Default | --- ## 2. UX Specification ### 2.1 Navigation Placement - **Location**: `Couple Admin Portal` → `Invitation` → `Event Sessions` - **Route**: `/app/couple/invitation/sessions` - **Rationale**: Inveetaire groups all invitation payload configurations under the `Invitation` parent navigation menu (`General`, `Media`, `Design`, `Message Template`). Adding `Event Sessions` under `Invitation` follows established design standards (`DS001`). ``` Sidebar Navigation └── ✉️ Invitation ├── • General ├── • Media ├── • Design ├── • Event Sessions <-- NEW (Phase 3) └── • Message Template ``` ### 2.2 Design Philosophy & Aesthetics - **Progressive Disclosure**: If an event has only 1 session, it displays as a clean, compact single-card. Multi-session options (`+ Add Session`) expand seamlessly when needed. - **Visual Hierarchy**: Cards grouped by the 3 core events. Each event card highlights session count, default badge, assigned guest count, and action controls. - **Design Tokens**: Standard Inveetaire DS001 Palette (Rose Gold `#D4A28C`, Slate borders, Warm Charcoal highlights). --- ## 3. Business Rules 1. **Strict Core Events**: Exactly 3 events exist per workspace (`Holy Matrimony`, `Tea Pai`, `Reception`). 2. **Minimum Session Rule**: Every wedding event MUST have at least 1 session at all times. Deleting the sole remaining session is strictly blocked. 3. **Default Session Uniqueness**: Every wedding event MUST have exactly ONE session marked as Default (`is_default = 1`). 4. **Automatic Default Reassignment**: Deleting a multi-session row reassigns all affected guests to the event's Default Session automatically (`ON DELETE SET NULL` DB fallback). 5. **Operational Scope Isolation**: Attendance (check-ins), RSVPs, QR Scanners, Analytics, and Dashboard counters remain aggregated strictly by `wedding_event_id` (Event-level). Sessions do NOT split check-in counters. --- ## 4. ASCII Wireframes ### 4.1 Main Event Sessions Page (`/app/couple/invitation/sessions`) ```text ========================================================================================== INVEETAIRE | Couple Admin Portal [ Workspace: Ahmad & Fatimah ] ========================================================================================== 👥 Guests | ✉️ Invitation > Event Sessions | 📊 Analytics | ⚙️ Settings ────────────────────────────────────────────────────────────────────────────────────────── Event Sessions Configure invitation schedules for your wedding ceremonies. Guests can be assigned to specific sessions inside Guest Management. ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ 💡 Quick Tip: If a ceremony has multiple shifts (e.g. Morning vs Afternoon), create │ │ multiple sessions here and assign your guests accordingly. │ └──────────────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ ⛪ 1. HOLY MATRIMONY [ + Add Session ] │ │ Venue: Grand Suite Ballroom | Date: Saturday, 12 Sept 2026 │ ├──────────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌────────────────────────────────────────────────────────────────────────────────┐ │ │ │ 🏷️ Session 1 [⭐ DEFAULT] 👥 45 Guests Assigned │ │ │ │ ⏰ 10:00 - 11:00 WIB │ │ │ │ 📍 Main Chapel, Level 2 │ │ │ │ [ Edit ] [ Delete (Disabled)]│ │ │ └────────────────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────────────────────────────┐ │ │ │ 🏷️ Session 2 👥 30 Guests Assigned │ │ │ │ ⏰ 11:30 - 12:30 WIB │ │ │ │ 📍 Main Chapel, Level 2 │ │ │ │ [ Make Default ] [ Edit ] [ Delete ]│ │ │ └────────────────────────────────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ 🍵 2. TEA PAI [ + Add Session ] │ │ Venue: VIP Pavilion Room | Date: Saturday, 12 Sept 2026 │ ├──────────────────────────────────────────────────────────────────────────────────────┤ │ ┌────────────────────────────────────────────────────────────────────────────────┐ │ │ │ 🏷️ Default Session [⭐ DEFAULT] 👥 15 Guests Assigned │ │ │ │ ⏰ 13:00 WIB │ │ │ │ 📍 VIP Pavilion Room │ │ │ │ [ Edit ] [ Delete (Disabled)]│ │ │ └────────────────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ 🍷 3. RECEPTION [ + Add Session ] │ │ Venue: Grand Suite Ballroom | Date: Saturday, 12 Sept 2026 │ ├──────────────────────────────────────────────────────────────────────────────────────┤ │ ┌────────────────────────────────────────────────────────────────────────────────┐ │ │ │ 🏷️ Default Session [⭐ DEFAULT] 👥 120 Guests Assigned │ │ │ │ ⏰ 18:00 WIB │ │ │ │ 📍 Grand Suite Ballroom │ │ │ │ [ Edit ] [ Delete (Disabled)]│ │ │ └────────────────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────────────┘ ========================================================================================== ``` ### 4.2 Modal: Add / Edit Session ```text ┌────────────────────────────────────────────────────────────────────────┐ │ Add Session — Holy Matrimony X │ ├────────────────────────────────────────────────────────────────────────┤ │ │ │ Session Name * │ │ [ Session 2 ] │ │ e.g. Session 2, Morning Shift, VIP Family │ │ │ │ Start Time * End Time (Optional) │ │ [ 11:30 WIB ] [ 12:30 WIB ] │ │ │ │ Venue / Room Override (Optional) │ │ [ Main Chapel, Level 2 ] │ │ Leave empty to use main event venue (Grand Suite Ballroom) │ │ │ │ Guest Notes / Instructions (Optional) │ │ [ Please arrive 15 minutes before ceremony start. ] │ │ │ │ [x] Set as Default Session for Holy Matrimony │ │ │ ├────────────────────────────────────────────────────────────────────────┤ │ [ Cancel ] [ Save Session ]│ └────────────────────────────────────────────────────────────────────────┘ ``` --- ## 5. Recommended Workflows ### 5.1 Create Session Workflow 1. Couple navigates to `Invitation` → `Event Sessions`. 2. Locates target event card (e.g. `Holy Matrimony`) and clicks `+ Add Session`. 3. Modal appears pre-filled with sensible defaults (e.g. Name: "Session 2", Start Time: Event Date + 1 hour). 4. Couple enters session details and clicks `Save Session`. 5. System validates fields, inserts record into `event_sessions`, updates list, and displays success toast. ### 5.2 Edit Session Workflow 1. Couple clicks `Edit` on an existing session card. 2. Modal opens with existing session values pre-populated. 3. Couple modifies desired fields (e.g. updates Start Time from 11:00 to 11:15). 4. Clicks `Save Changes`. 5. System updates `event_sessions`. All assigned guests automatically see the updated time on their digital invitations on next load. ### 5.3 Delete Session Workflow 1. Couple clicks `Delete` on a session card. 2. **Rule Evaluation**: - If session is the **only session** for that event: Delete button is disabled or action blocked with alert: *"Events must have at least one session."* - If session has **assigned guests**: Confirmation modal alerts: > ⚠️ **Delete Session 2?** > 30 guests are currently assigned to this session. Deleting it will automatically reassign those guests to the Default Session (**Session 1 @ 10:00 WIB**). 3. Couple clicks `Confirm Delete`. 4. System deletes session row. DB foreign key `ON DELETE SET NULL` clears `guest_events.event_session_id`, reverting guests to default session transparently. ### 5.4 Switch Default Session Workflow 1. Couple clicks `Make Default` on a non-default session. 2. System updates target session to `is_default = 1` and resets previous default session to `is_default = 0` atomically. --- ## 6. Sorting & Ordering Strategy - **Primary Ordering**: Chronological by `start_time ASC`. - **Secondary Ordering**: `sort_order ASC` (for sessions sharing identical start times). - **Rationale**: Invitations are inherently chronological timelines. Automatic start-time sorting keeps the interface intuitive without forcing manual drag-and-drop maintenance on couples. --- ## 7. Validation Checklist | Rule | Trigger | Enforcement Mechanism | Error Message | |---|---|---|---| | **Required Fields** | Form Submit | Client JS & Server Validation | *"Session Name and Start Time are required."* | | **End Time Sanity** | Form Submit | Server Validation | *"End time must be after start time."* | | **Minimum Session Guard** | Delete Action | Server Validation & UI Disabled | *"Cannot delete the sole remaining session for an event."* | | **Unique Session Name** | Form Submit | Server Validation | *"A session named '[Name]' already exists for this event."* | | **Time Overlap** | Form Submit | Soft Warning (Non-blocking) | *"Notice: This session overlaps with Session 1 (10:00 - 11:15)."* | | **Single Default** | Set Default | Server Transaction | Automates atomic update of `is_default` flags. | --- ## 8. Edge Cases & Handling 1. **Edge Case: Delete Default Session** - *Handling*: If a couple deletes a session marked as default, the system automatically promotes the earliest remaining session (by `start_time`) to `is_default = 1`. 2. **Edge Case: Editing Session Time for Published Invitations** - *Handling*: Invitation renderers pull `start_time` dynamically via `LEFT JOIN event_sessions`. Updated session times reflect instantly on public invitations without requiring link regeneration. 3. **Edge Case: Guest assigned to deleted session** - *Handling*: DB `ON DELETE SET NULL` sets `guest_events.event_session_id = NULL`. `PublicInvitationModel::getAssignedEvents()` uses `COALESCE(es.start_time, default_es.start_time, we.event_date)`, falling back to default session seamlessly. --- ## 9. Future Scalability ### Architectural Flexibility The database architecture (`event_sessions` foreign-keyed to `wedding_events.id`) natively supports multi-session configuration for **Tea Pai** and **Reception** without any schema alterations. ``` wedding_events (id: 25 - Holy Matrimony) ──► event_sessions (Sesi 1, Sesi 2) wedding_events (id: 26 - Tea Pai) ──► event_sessions (Familia, VIP) wedding_events (id: 27 - Reception) ──► event_sessions (Shift 1, Shift 2) ``` Adding sessions to Tea Pai or Reception uses the exact same UI controller, model endpoints, and guest assignment logic developed in Phases 1 & 2. --- ## 10. Summary & Recommendation 1. **Navigation**: Place under `Invitation` → `Event Sessions` (`/app/couple/invitation/sessions`). 2. **UI Approach**: Event Card list with collapsible session tables and modal-based Create/Edit forms. 3. **Safety**: Enforce single-session minimum guard and automated default session fallback. 4. **Implementation Phase**: Ready to proceed with Phase 3 coding upon approval.