UI & Guest Experience — Schema-Driven Hotel Interfaces

Status: Frontend Architecture
Sources: UI Bolt-On Guide & Declarative Component Blueprints, AGENTS.md — Sovereign OS / Cosmic Circuit mandates 11 & 12 (no hardcoded scenarios, no un-production-ready hardcoded card values)

1. Paradigm — Headless Schema-Driven Execution Shell

The hotel UI does not hardcode business workflows, wizards, or approval policies. It operates as a headless shell driven by declarative JSON schemas from NATS JetStream KV (SOVEREIGN_TEMPLATES, SOVEREIGN_LOOKUPS):

Apache Camel / NATS KV (:8181)
  GET /services/playbook/spec/{playbook_id}
  → Declarative JSON Schema (fields, validation, constraints)
  → UI Layout Manifest (sections, widgets, action buttons)
      ▼ JSON Specification
Sovereign Frontend Component Tree
  <PlaybookRunner playbook="housekeeping.v1">
    <PlaybookHeader title, stage_indicators, sla_badge />
    <SchemaDrivenForm schema={current_step.schema} />
    <ActionToolbar buttons={current_step.actions} onSubmit={handleStep} />
    <PoCEAuditDrawer session_token={session.id} receipts={steps} />

2. Strict Frontend Rules

Zero hardcoded status or metrics. UI cards, dashboards, and badges never display dummy numbers (no fake 98.4%, KES 18,500, 12 active rooms). Data comes from live backend API responses, or the UI renders honest skeleton loaders / empty states.
Color palette adherence (purple ban). No purple/violet. Primary: Deep Obsidian (#090D16), Slate Dark (#0F172A), Emerald Green (#10B981) for confirmed/active, Amber (#F59E0B) for pending approvals.
Live streaming over polling. Components bind to NATS WebSocket subjects (workflow.{property}.{playbook_id}.*) for reactive state updates — no polling loops.

3. Hotel UI Component Blueprints

Component	Playbook	Purpose
`<FolioCart />`	H-1 Reservation & Folio	Line-item folio editor, running total, cost-center allocation, threshold badge (TIER_1/2/3) as items are added
`<HousekeepingTaskCard />`	H-2 Housekeeping	Room, attendant, checklist items, photo capture, status (ASSIGNED/IN_PROGRESS/READY), inspector sign-off
`<WorkOrderCard />`	H-3 Maintenance	Asset, fault, priority, technician, parts log, OpenMAINT ref, expert sign-off gate
`<RequisitionCart />`	H-4 Procurement	Catalog picker, line items, dynamic total, approval-tier indicator, dual-custody signer list
`<EventBookingForm />`	H-5 Events	Function space, dates, F&B minimum, guest count, AV needs, deposit status
`<MoodBoardCanvas />`	H-6 Event Design	Infinite canvas, pin cards (MinIO assets + SHA-256), palette strip, Gotenberg PDF export
`<DiscussionThread />`	H-7 Staff Comms	Synapse Matrix room bridge, nested comments, "Promote to Formal Proposal"
`<IncidentReport />`	H-8 Incident	Location, severity, reporter, photo evidence, escalation ladder
`<StageGateApprovalModal />`	Universal	Dual-custody approval with required signers, evidence hash verification, FIDO2/security-key authorize

4. Real-Time State Synchronization

Frontend connects via NATS WebSocket (nats.ws), subscribes to workflow.{property}.{playbook_id}.*, and updates reactively on PoCE step events, room status changes, and approval transitions — no polling.

5. Honest Feedback States

Loading: Shimmering skeleton bars matching expected card aspect ratios. No spinner masks or fake percentage counters.
Empty: Honest statement (e.g., "No housekeeping tasks pending for your shift.") with direct action button ("+ Create Task").
Outage: Clear banner ("Connectivity to Sovereign Core degraded. Mutations are disabled until connection restores."). No synthetic fallbacks.

6. Branding

The UI is white-label. Hotel branding (logo, colors within the approved palette, property name) is applied as a theme overlay — never baked into workflow logic. The Sovereign Console (apps/sovereign-console :10300) is the reference SPA host.