OSIT-AE-App-Svelte/documentation/MODULE__AE_Events_PressMgmt_Launcher.md

# Aether Events — Presentation Management & Launcher

Notes on setup, workflow, configuration, and onsite operation for the Events Presentation
Management module and the companion Launcher (podium display) system.

---

## Overview

The Presentation Management (Pres Mgmt) module handles the full lifecycle of conference
content: sessions, presentations, presenters, presentation files, and room/location
assignments. The Launcher module provides the podium display interface that runs on each
session room's kiosk machine.

These two modules are deployed together — Pres Mgmt is the back office, Launcher is the
front-of-house display. Every client show is at least slightly customized. Some clients
have extensive presenter/presentation data; others just have sessions and files. The
platform is flexible enough to handle the full range.

**Reference clients (current/repeat):**
- **BGH** (Business Group on Health) — most basic setup; session-only, no named Presenters
- **LCI** (Lean Construction Institute) — most complex current setup
- **AAPOR**, **ASCM**, **CMSC** — other active/repeat clients

**Module paths:**
- Pres Mgmt: `/events/[event_id]/pres_mgmt`
- Launcher: `/events/[event_id]/launcher`

**Key source directories:**
- `src/routes/events/[event_id]/(pres_mgmt)/`
- `src/routes/events/[event_id]/(launcher)/`
- `src/lib/ae_events/` — data types and API functions for all event objects

---

## Data Model

### Object Hierarchy

```
Event
├── Event File (walk-in/out, hold slides for the whole event)
├── Location (physical room — assigned to Sessions, not the other way around)
├── Track (optional grouping; rarely used — see note below)
└── Session (time block; Location assigned here, but may be unset initially)
    ├── Session File (moderator slides, group/hold slides for this session)
    └── Presentation (a talk within the session; must belong to exactly one Session)
        └── Presenter (belongs to exactly one Presentation)
            └── Presenter File (their slides/materials — the common case)
```

> **Import note:** When program data is initially imported (sessions, presentations,
> presenters), Locations are often not assigned to Sessions yet — rooms may not be
> finalized or the venue's room list may not be set up in Aether. Location assignment
> typically happens as a separate step once the room list is confirmed.

### Relationships

- **Session → Location:** Many-to-one. A Session is assigned to one Location; a Location
  hosts many Sessions across the event timeline. Location may be null initially.
- **Presentation → Session:** Many-to-one. A Presentation belongs to exactly one Session.
  A Session can have many Presentations (or none, for session-only setups).
- **Presenter → Presentation:** Many-to-one. A Presenter belongs to exactly one Presentation.
  Optionally linked to an `event_person_id` for cross-referencing the person record.
- **Event File:** Can be attached at any level — Presenter, Presentation, Session,
  Location, or Event. See the File Attachment Levels table.

### File Attachment Levels

Files (`event_file`) can be attached at five levels:

| Level | When Used | Typical Content |
|---|---|---|
| **Presenter** | 99% of the time for individual speakers | Their PowerPoint/PDF/video |
| **Session** | Moderator slides; group/hold content for a specific session | "Session 3 — Group Discussion.pptx" |
| **Location** | Walk-in/out or hold slides for a room across all sessions | Looped PPTX playing between sessions |
| **Event** | Walk-in/out or hold slides used everywhere | Looped PPTX; branding overlay |
| **Presentation** | File attached to the presentation record itself (less common) | Varies |

### Key Objects

| Object | Table | Purpose |
|---|---|---|
| Session | `event_session` | Time block; Location and datetime range assigned here |
| Location | `event_location` | Physical room; the Launcher's primary unit of display |
| Presentation | `event_presentation` | A talk within a session; belongs to exactly one Session |
| Presenter | `event_presenter` | Person linked to exactly one Presentation; optionally linked to `event_person` |
| Event Person | `event_person` | Person record within the event context |
| Event File | `event_file` | Uploaded file; attached at Presenter, Presentation, Session, Location, or Event level |
| Event Device | `event_device` | Registered Launcher kiosk (Electron native instance) |
| Event Track | `event_track` | Optional content grouping (see note below) |

### Event Tracks

The API supports Event Tracks — an optional grouping layer above Sessions. Used twice
historically; could have been omitted both times. Tracks may become genuinely useful for
larger events running many parallel Locations where thematic grouping helps navigation.
Not in active use currently and not wired into the standard Pres Mgmt UI workflow.

### Session → Location

The Launcher's primary display unit is the Location. It shows the active Session for that
Location based on `datetime_start` / `datetime_end` or manual selection. A Location hosts
many Sessions over the event's run; typically only one is active at a time.

---

## Client Setup Variation

There are no rigid "modes" — events are configured with as much or as little structure
as needed. The platform handles the full range:

**Minimal setup (BGH):**
Sessions have room and time info. No Presentations or Presenters defined.
Staff upload files directly at the session or location level onsite.

**Mid-range setup:**
Sessions defined with named Presentations. Presenters may or may not be tracked.
Mix of pre-uploaded and onsite files. QR codes may be used for quick session/presenter lookup.

**Full setup (LCI):**
Sessions, Presentations, Presenters all defined and managed. External ID labeling
(e.g., "LCI Member ID"). Agreement tracking for presenters. Files managed per-presenter.
Launcher linked from Pres Mgmt views.

The config that drives this is `event.mod_pres_mgmt_json` — see the Configuration section.

---

## Speaker Ready Room (SRR)

The Speaker Ready Room is a dedicated space where presenters check in and staff manage
content before it goes live in the session rooms. Setup varies by client:

- **Small/private:** Only a few client staff and OSIT. Not open to presenters at large.
- **Open SRR:** Open to all presenters as long as sessions are running. People come and go
  all day — reviewing silently, editing with a group, practicing at a station.

### SRR Practice Stations

Stations mirror the session room setup exactly:
- Same Mac laptop model and adapter/dongle configuration as the podiums
- Projector and screen (same as session rooms where possible)
- Launcher running in Native (Electron) mode — cached files open immediately
- Full dry-run capability: load their file, start the deck, confirm everything works

### Remote Monitoring

SRR staff typically monitor the session room Launchers in real time via **VNC or RustDesk**.
This lets one person watch multiple podium displays simultaneously without being in each room.

### QR Codes (Session and Presenter)

QR codes are available for Sessions and Presenters and have been useful onsite for quick
lookups — scanning a code takes staff directly to the session or presenter record.
Whether to enable this depends on the SRR flow for each show. It gets toggled on or off
per event via config.

### SRR Staffing Roles

| Role | Access Level | Typical Tasks |
|---|---|---|
| OSIT Staff | `trusted_access` or higher | Upload files, edit sessions/presentations, manage devices, monitor via VNC |
| Client Staff | `authenticated_access` | Upload files, view session list |
| Presenter (self-service) | `authenticated_access` (if enabled) | Upload their own files via QR link |

### SRR Workflow — Day-of-Show

1. **Presenter checks in** — staff looks up their session(s) in Pres Mgmt
2. **File upload** — staff or presenter uploads file to the correct presenter/session record
3. **File verification** — staff opens the file on a practice station to confirm it renders
4. **Launcher sync** — file appears in the Launcher within the next polling cycle
5. **Presenter proceeds to room** — podium kiosk already has the file cached

---

## File Upload Workflows

### Pre-Show (Remote / Staff Ahead of Time)

Files can be uploaded anytime before the event via the Pres Mgmt web UI:
1. Navigate to the presenter, session, or appropriate level
2. Use the file upload panel (drag & drop or browse)
3. File is stored server-side and immediately available to the Launcher

Some clients enable presenter self-upload via a direct link (requires `authenticated_access`).
Controlled per-event via config.

### Day Before — SRR Setup

For higher-volume shows, the SRR opens the day before the event:
- Pre-uploaded files are already loaded and can be verified
- Early-arriving presenters check in; staff upload their files
- Electron Launcher instances on podium Macs begin pre-caching files overnight
- Problems (corrupt files, wrong format, wrong codec) surface with time to fix them

### Live Onsite Upload

For late arrivals and last-minute changes:
1. Presenter arrives at SRR (or sends file via USB/email to staff)
2. Staff uploads via Pres Mgmt web UI
3. File propagates to Launcher within one polling cycle (~30 seconds on fast networks)
4. VNC or RustDesk confirms the podium received the file before the presenter walks in

---

## Onsite Operation — Managing 4–12 Parallel Rooms

### Overview Page

The Pres Mgmt overview (`/events/[event_id]/pres_mgmt`) shows:
- All sessions, filterable by location and time
- File status per session
- Quick links to each session's file management

For events with multiple parallel rooms, filtering by location and time block is essential
for SRR staff staying on top of what's active right now.

### Per-Room Workflow

Each room/location has its own Launcher display:
- `/events/[event_id]/launcher` → select location → Launcher for that room
- The Launcher shows the active session based on the current time or manual selection
- VNC/RustDesk gives SRR staff a real-time view of all podiums simultaneously

### Session Display Timing

Ideally, sessions would automatically show and hide based on `datetime_start` /
`datetime_end` — appearing a configurable number of minutes before the session starts
and disappearing after it ends. This is a planned/desired behavior. In practice:

- Some clients run tight schedules and could rely on time-based transitions
- Others drift significantly from the published schedule; time-based auto-advance
  would cause more problems than it solves
- Currently, session transitions can be managed manually via Launcher controls

> **TODO (future):** Configurable `show_before_minutes` / `hide_after_minutes` per event
> so well-run shows can automate transitions while looser shows stay manual.

### Device (Laptop) Assignment

Each Launcher kiosk Mac is registered as an `event_device` and typically assigned to one
Location for the duration of the event. However, laptops do get moved:
- Venues add or lose rooms as spaces are reconfigured
- A session room may open for one day only
- Devices can be reassigned to a different Location in the `event_device` record as needed

The Electron app reads its location assignment from the API at startup, so reassigning a
device takes effect on the next launch (or app restart).

---

## Alert Fields

Sessions, Presenters, and Locations each have alert fields that can display a visible
notice in the Pres Mgmt UI and/or the Launcher.

Useful for:
- "Presenter requested no recording"
- "Room change — moved to Hall B"
- "File not received — follow up"
- "AV note: needs confidence monitor"

> **Status:** Alert fields exist but the implementation and display behavior needs review
> and cleanup. Not a blocking issue for BGH next week — revisit for a future show.

---

## Launcher Module

### Operational Modes

| Mode | Use Case | File Handling |
|---|---|---|
| **Default** | Browser on any machine | Files downloaded on demand |
| **Onsite** | Browser on event network | Faster polling; browser-managed files |
| **Native** | Electron app on dedicated podium Mac | Background pre-cache; atomic file handover |

For production onsite use, **Native mode on Mac laptops** is the target. The Electron
app pre-caches all session files in the background so presentations open instantly without
a network round-trip at the moment of launch.

### Native Mode — Electron App

- **Repo:** `~/OSIT_dev/aether_app_native_electron/`
- **Platform:** macOS (primary); Linux/Windows as fallback
- **Seed config:** `seed.json` (Device ID + API key) — loaded at startup
- **File cache:** `~/Library/Caches/OSIT/file_cache/` (hashed by SHA-256)
- **Doc:** `documentation/PROJECT__AE_Events_Launcher_Native_integration.md`

The Electron app zero-configs itself:
1. Reads `seed.json` → gets device code
2. Calls Aether API → pulls device config and location assignment
3. Navigates directly to the Launcher for that location
4. Begins pre-caching session files in the background

### Launcher Display Views

| View | Shown When |
|---|---|
| Session view | Active session with session-level files |
| Presentation view | Active session with named presentations |
| Presenter view | Presentation selected; shows presenter bio/photo |
| Poster/group view | Special layout for poster sessions |
| Screensaver | No active session; idle state |

### File Opening (Native Mode) — Safe Handover

1. Verify SHA-256 hash in permanent cache
2. Atomic copy to system `[tmp]` directory
3. Rename to original filename (e.g., `Abstract_101.pptx`)
4. OS opens the file (Keynote, PowerPoint, Preview, etc.)

Versioning is handled automatically: when a presenter uploads an updated file, the new
hash is cached separately and the old one remains intact.

---

## Configuration — `mod_pres_mgmt_json`

The event's Pres Mgmt behavior is controlled by `event.mod_pres_mgmt_json`.

> **Note:** The config schema is being cleaned up — see
> `documentation/PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` for the canonical
> `PressMgmtRemoteCfg` interface and naming conventions.

### Convention

| Prefix | Default state | Meaning |
|---|---|---|
| `hide__` | `false` = visible | Feature is ON by default; set `true` to suppress |
| `show__` | `false` = hidden | Feature is OFF by default; set `true` to enable |

### Common Config Keys

| Key | Default | Notes |
|---|---|---|
| `lock_config` | `false` | `true` = force remote→local sync; prevents user overrides of local config |
| `hide__session_code` | `false` | Hide session code column/field |
| `hide__session_description` | `false` | Hide session description field |
| `hide__session_location` | `false` | Hide location field on session view |
| `hide__session_datetime` | `false` | Hide datetime fields |
| `hide__presentation_code` | `false` | Hide presentation code |
| `hide__presenter_code` | `false` | Hide presenter code |
| `hide__location_code` | `false` | Hide location code |
| `show__launcher_link` | `false` | Show direct Launcher link in session view |
| `show__session_qr` | `false` | Show QR code for session (SRR lookup) |
| `show__presenter_qr` | `false` | Show QR code for presenter (SRR lookup) |
| `label__person_external_id` | `null` | Override label for external ID field (e.g., `"Member ID"`) |
| `label__session_poc_name` | `null` | Override label for session POC (e.g., `"Champion"`) |
| `file_purpose_option_kv` | `{}` | Key-value map of file purpose options (e.g., `{"ppt": "PowerPoint", "pdf": "PDF"}`) |

### Per-Show Config Examples

**BGH (session-only, minimal; no named Presentations or Presenters):**
```json
{
  "lock_config": false,
  "hide__presentation_code": true,
  "hide__presenter_code": true
}
```

**LCI (full setup, member ID label, Launcher link enabled):**
```json
{
  "lock_config": true,
  "label__person_external_id": "LCI Member ID",
  "show__launcher_link": true
}
```

> Admin must currently edit `mod_pres_mgmt_json` directly in the DB or via the event
> settings page. A proper Config UI is planned — see `PROJECT__AE_Events_PressMgmt_Config_Cleanup.md`.

---

## Route Map

| URL | Purpose |
|---|---|
| `/events/[id]/pres_mgmt` | Overview — sessions list, search, filter by location |
| `/events/[id]/pres_mgmt/config` | Config editor (admin only) |
| `/events/[id]/session/[session_id]` | Session detail — files, presentations, timing, alert |
| `/events/[id]/presenter/[presenter_id]` | Presenter detail — bio, files, agreement, alert |
| `/events/[id]/location/[location_id]` | Location detail — session schedule for this room, alert |
| `/events/[id]/locations` | All locations list |
| `/events/[id]/reports` | Reports — sessions, presenters, files |
| `/events/[id]/launcher` | Launcher home — select location |
| `/events/[id]/launcher/[location_id]` | Launcher display for a specific room |

---

## Device Management

Each Electron kiosk is registered as an `event_device` record:
- `code` — matches the device's `seed.json` code
- `name` — human-readable (e.g., "Ballroom A Podium")
- `data_json.location_id` — the `event_location_id` this device is assigned to

Devices can be managed in Pres Mgmt (`/events/[id]/device/device`). Location reassignment
takes effect on the next Electron app launch.

---

## Access Levels

| Feature | Minimum Access |
|---|---|
| View pres_mgmt overview | `authenticated_access` |
| Upload files | `authenticated_access` |
| Edit sessions / presentations | `trusted_access` |
| Edit config | `administrator_access` + `edit_mode` |
| View Launcher display | `authenticated_access` |
| Manual session selection in Launcher | `trusted_access` |
| Device management | `administrator_access` |

---

## Pre-Show Checklist

### 1–2 Weeks Before

- [ ] Event created in Aether with correct dates
- [ ] `mod_pres_mgmt_json` configured for this client's needs
- [ ] Locations (rooms) created and named
- [ ] Sessions created, assigned to locations, datetime ranges set
- [ ] If using Presentations/Presenters: records imported or entered
- [ ] File purpose options configured in `file_purpose_option_kv`
- [ ] Launcher devices registered (`event_device` records with correct codes)
- [ ] Device-to-location assignments confirmed
- [ ] Decide: QR codes for Sessions / Presenters needed? Enable/disable in config

### Day Before (SRR Setup)

- [ ] Mac laptops at podiums booted and Electron app running
- [ ] Each podium confirms it loaded the correct location's Launcher
- [ ] SRR practice stations confirmed — projector, same Mac/dongle setup as session rooms
- [ ] Pre-loaded files verified in Launcher (open at least one per room to test Safe Handover)
- [ ] SRR staff briefed on upload workflow and VNC/RustDesk monitoring setup
- [ ] VNC/RustDesk connections established to all podium displays

### Day of Show

- [ ] Confirm all session times in Aether are accurate before first session
- [ ] Monitor SRR queue — upload files as presenters check in
- [ ] Verify each file opens on a practice station before the presenter walks to their room
- [ ] Monitor podium displays via VNC/RustDesk — flag any stuck or offline devices

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Session not showing in Launcher | Session datetime wrong or location not assigned | Verify session location and datetime range |
| File uploaded but not in Launcher | Polling cycle lag; or file attached at wrong level | Wait one cycle; check that file is attached to session/location (not just a presenter record) if using session-only setup |
| Electron app shows wrong location | Device code mismatch or stale device config | Re-check `event_device` record; restart Electron app |
| File opens slowly at podium | Not in native cache yet | Check background sync in Launcher; pre-cache may not have completed |
| File won't open | Corrupt upload, wrong format, or missing codec on Mac | Test on SRR practice station; re-upload or convert |
| Session out of sync with schedule | Timing drifted; manual advance needed | Use Launcher controls to manually select the current session |
| Alert field not showing | Alert fields need implementation review | Known — lower priority than active operations |
| `lock_config: true` resets local changes | Expected behavior — remote config wins | Change the remote config in `mod_pres_mgmt_json` |
| Device needs to move to different room | Location reassigned mid-event | Update `data_json.location_id` on `event_device` record; restart Electron app on that machine |