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. Staff can use the Force Sync Location button in the Launcher config to immediately queue all files for the room's schedule.
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.

Download Priority & Room Readiness

To ensure the podium is ready for the day's first sessions, the Launcher sync engine uses a 4-tier chronological sorting priority:

1. Global Assets: Event and Location level files (branding, walk-in slides) are cached first.
2. Session Schedule: Files for the earliest sessions in the room are prioritized.
3. Presentation Order: Within a session block, speakers are prioritized by their scheduled start time.
4. First-In Fairness: When times are equal, older uploads are prioritized over late revisions.

Operators can manually trigger a full pre-sync of all location materials via the Force Sync Location button in the Launcher configuration (Sync Engine section).

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

Configurable launch behavior: The file-open behavior is driven by a Launch Profile, not just a command string. Profiles are stored per file extension in event_device.data_json.launch_profiles (device-level config) or event.launcher.launch_profiles (event-level fallback). The built-in Svelte defaults are the final fallback and are documented below. A profile can choose the app, display mode, open command, and post-open automation. The resolved native template uses {{path}} as the file path placeholder; AppleScript or shell: prefixed commands are both supported. No Electron rebuild is required to change how files open — edit config in Aether and it applies immediately. See PROJECT__AE_Events_Launcher_Native_integration.md Section 8.

Built-In Default Launch Profiles

These are the initial built-in defaults shipped with the Launcher. They are the Svelte-side fallbacks used when neither device config nor event config defines a profile for the file extension. Each canonical profile can have multiple extension aliases. post_delay_ms is part of the profile object, so a device-specific launch_profiles[profile].post_delay_ms override can tune it later without changing the profile table.

Profile name	Extension aliases	Default app	Display mode	Post delay	Notes
powerpoint_mac_extend	pptx, ppt	Microsoft PowerPoint for macOS	extend	1000ms	Open in the presentation app and extend to an external display if one is present.
keynote_mac_extend	key	Keynote	extend	1000ms	Keynote slideshow on the external display if available. Post-script polls count of documents > 0 before starting — handles slow file load on cold start.
libreoffice_mac_extend	odp	LibreOffice for macOS	extend	1000ms	LibreOffice Impress for OpenDocument presentations.
acrobat_mac_mirror	pdf	Adobe Acrobat for macOS	mirror	1000ms	PDF handout / deck view uses mirrored display.
vlc_mirror	mp4, mkv, mp3, m4v, m4a, webm, wav, aac, flac, mov, mpeg, avi, flv, ogg, ogv, wmv	VLC for macOS	mirror	1000ms	Media playback is mirrored so the room sees the same output as the operator. Uses --no-play-and-exit so playback ends on the last frame instead of closing video output.
powerpoint_win_extend	pptxwin, pptwin	PowerPoint for Windows (Parallels)	extend	1500ms	Windows PowerPoint profile for Parallels-based rooms. Higher base delay to account for Parallels VM startup latency.
libreoffice_win_extend	odpwin	LibreOffice for Windows	extend	1500ms	Windows LibreOffice profile for Parallels-based rooms.
acrobat_win_mirror	pdfwin	Adobe Acrobat for Windows (Parallels)	mirror	1500ms	Windows PDF profile for mirrored display rooms.
url_web	url	Browser / Event File web presentation	extend	n/a	Web-based presentations are handled as Event File URLs rather than cached local files.

Post-open automation timing: All profiles with a post_script use a polling loop rather than a fixed sleep — the AppleScript waits up to ~7.5 s for the target process to become frontmost before firing the automation keystroke. The post_delay_ms value is a minimum baseline before polling begins. Overridable per profile via launch_profiles[profile].post_delay_ms in event_device.data_json.

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):

{
  "lock_config": false,
  "hide__presentation_code": true,
  "hide__presenter_code": true
}

LCI (full setup, member ID label, Launcher link enabled):

{
  "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