App Guide and Runtime

Use This Reference Carefully

Use this guide when event work may happen on local devices, offline files, or LAN-only tools instead of the live online dashboard. In this guide, App Guide and Runtime narrows that work to actual FPH LAN EMS app guide covering runtime, SQLite, SPA shell, local HTTPS, DNS/mDNS, LiveKit, Android wrapper, packaging, and certification. Because this is a reference page, read it as part of the EMS LAN learning path rather than as an isolated checklist.

EMS LAN keeps an event moving when internet access is unreliable, but it also creates a second place where event records can change. Read the page for the decision it helps a person make, then use the steps and checks as a steady path from context to action to proof.

What This Reference Collects

This page is for checking details. Use it to confirm names, routes, records, fields, or certification points before relying on memory. The intended readers are Server operators, Support leads, and Release reviewers. If the guide names a dashboard route, service area, export, or record type, treat that name as a pointer to real operational responsibility.

• Primary surface or service: /login, /control-room, /admin/:eventId/:surface, and /workspace/:eventId/:surface.
• Records or contracts involved: .lan-data, SQLite database, Runtime logs, TLS certificates, and LiveKit credentials.
• Main care point: Watch for losing track of which file, device, person, or import is trusted while attendee, staff, inventory, POS, or check-in records change offline.
• Proof worth keeping: event ID, snapshot filename, export time, device owner, import summary, sync-history entry, reconciliation count, and supervisor note.

How To Find The Right Entry

1. Search for the exact name or route: Begin by naming the EMS LAN situation, the owner, and the exact item involved in App Guide and Runtime.
2. Read the surrounding note, not only the matching line: Use /login, /control-room, /admin/:eventId/:surface, and /workspace/:eventId/:surface to connect the words on the page to the screen, file, service route, or record that people actually use.
3. Compare the reference with the live screen, file, or service evidence: Keep .lan-data, SQLite database, Runtime logs, TLS certificates, and LiveKit credentials in view so the work stays tied to the records or contracts it can affect.
4. Save the evidence that proves the entry was checked: Before handing off, save proof such as event ID, snapshot filename, export time, device owner, import summary, sync-history entry, reconciliation count, and supervisor note so the next lead can tell which file and device state are trusted.

Confirm The Reference Still Matches Reality

You are ready to use the rest of this page when the purpose, owner, affected information, and proof are all clear enough for a second person to review.

1. Scope is named: The work is tied to the correct page, event, report, route, file, person, or record.
2. Impact is understood: The operator can explain the effect on offline files, check-in access, staff rosters, inventory counts, POS totals, and import history.
3. Proof is findable: The handoff points to evidence that the next lead can tell which file and device state are trusted.

End-to-end operator runbook

Use this numbered runbook when auditing or explaining the actual LAN app.

1. Step 1 - Identify the thing being verified. Confirm you are looking at the fph-lan-ems repo, not only the partner dashboard offline snapshot exporter. This avoids missing LAN-only features.
2. Step 2 - Translate the technical name into plain language. Check README, about.md, src/lib/surfaces.ts, src/lib/server/api.ts, communications stores, native wrapper files, runtime scripts, and certification tasks. This gives the full product scope.
3. Step 3 - Match the route, file, or record to real workflow. Map the app into operator areas: startup/import, admin surfaces, workspace surfaces, local API, communications, native wrapper, machine clients, runtime services, and certification. This turns source into docs.
4. Step 4 - Collect enough evidence to avoid guessing. Include LAN-only features such as local communications, local users, machine tokens, Control Room, LiveKit, local HTTPS, DNS/mDNS, Android permissions, and package launchers. This prevents docs from looking like only offline check-in.
5. Step 5 - Confirm implementation and docs agree. Confirm docs pages and navigation mention these actual repo capabilities. This proves the audit covered the real app.
6. Step 6 - Send the result to the right owner. Re-run docs validation and keep TASK003 updated when actual LAN features change. This keeps docs aligned with the product.

Runtime components

Component	Actual repo evidence
Astro server-mode app	astro.config.ts with Node adapter.
Local Hono API	src/pages/api/[...route].ts delegates to src/lib/server/api.ts.
SQLite persistence	.lan-data/lan.db through src/lib/server/db/*.
Admin and workspace SPA shell	/admin/:eventId/:surface, /workspace/:eventId/:surface, src/lib/spa-router.ts.
Surface registry	src/lib/surfaces.ts.
Local auth	src/lib/server/local-auth.ts, bootstrap credentials, secure cookies on HTTPS.
Machine clients	src/lib/server/machine-tokens.ts, event-bound bearer tokens.
Communications	channels, DMs, groups, pins, reactions, attachments, voice notes, LiveKit, PTT, notifications.
Local HTTPS and DNS	runtime scripts for generated certificates, DNS, and mDNS hostnames.
Android wrapper	Capacitor project and native plugin bridge.
Release packaging	pnpm package:*, Windows package scripts, Android build scripts.

Actual admin surfaces

Attendee Rego, Dealers Den Rego, Roster, Live Shift Tracker, Rego Analytics, Inclusion Claim, Inventory Analytics, Inventory Tracking, Local User Accounts, Machine Tokens, and Communications.

Actual workspace surfaces

Check-In, Inclusion Claim, Point of Sales, Inventory Analytics, Staffing, Volunteering, and Communications.

Certification signals

The LAN repo includes certification tasks through TASK015. TASK014 is the full-surface gate and records backend, hosted browser, APK WebView, module, control, and event-day certification evidence.