# 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.
