Vertical platform expansion

Status: Living document — branch fluxy (July 2026)
Scope: ROADMAP §5.3–5.4 — FluxyHealth, FluxyEdu, FluxyEvent, FluxyFinance, Cross-Reality Continuity
Binding decisions: ROADMAP.md — Architectural Decisions Log
Expansion layer detail: platform-expansion-layer.md

Executive summary

Fluxy is repositioned from “chat SDK” to a realtime interaction platform where the room remains the central primitive. Chat, video, collaboration, streaming, game backends, IoT, and industry verticals are composable capabilities registered on a shared room kernel—not separate products with duplicated auth or event models.

This document records:

1. An audit matrix (claim → code → UI → readiness).
2. Current vs target architecture and capability/event contracts.
3. Vertical blueprints (Edu first, then Health, Event, Finance, Continuity).
4. Console IA and landing narrative migration.
5. A prioritized backlog with acceptance criteria and honesty gates.

Golden rule: Nothing is labeled production unless persistence, authorization, tenancy, and tests exist. Client-only in-memory engines are prototype or demo, never implied backend.

Positioning

Chat stays the fulcrum (membership, messages, agents, webhooks). Verticals add domain events (attendance, consent, tickets, market alerts) on the same envelope.

Audit matrix (summary)

Severity: P0 security/correctness, P1 misleading UX or data integrity, P2 quality/gaps, P3 polish.

Evidence paths:

• Kernel: packages/sdk/src/vertical-platform.ts, vertical-workflows.ts
• Tests: vertical-platform.test.ts, vertical-workflows.test.ts
• Console IA: apps/dashboard/app/components/console-nav.ts
• Studios: apps/dashboard/app/components/vertical-studio.tsx
• Products: apps/dashboard/app/game, iot, stream/demo

Current vs target architecture

Current (branch fluxy)

flowchart TB
  subgraph Client
    UI[Dashboard vertical studios]
    SDK[@fluxy-chat/sdk]
    VP[vertical-platform + workflows]
    Mod[fluxy-game / stream / iot / crdt]
  end
  UI --> SDK
  SDK --> VP
  SDK --> Mod
  Mod -.->|in-memory| VP
  Worker[apps/worker DO + D1] -->|chat core| SDK

Target

flowchart TB
  subgraph Edge
    DO[Room DO - authority]
    Policy[Policy engine RBAC/ABAC]
    D1[(D1 audit / retention)]
    Adapters[SFU FHIR Ticketing Market IoT]
  end
  subgraph Client
    SDK[@fluxy-chat/sdk ports]
    UI[Console + vertical studios]
  end
  UI --> SDK
  SDK -->|versioned events| DO
  DO --> Policy
  DO --> D1
  DO --> Adapters

Capability model

Capabilities are registered on RoomKernelConfig with CapabilityDefinition: id, readiness, policy (roles, retention, consent).

Event envelope (v1)

All vertical workflow publishes use:

• eventId, workspaceId, roomId, type, actor, occurredAt, schemaVersion: 1, idempotencyKey, payload

Tenant mismatch throws; duplicate idempotencyKey returns existing event.

Vertical blueprints

FluxyEdu (priority 1 — MVP path)

Journey: Create class → live session → knowledge check → breakouts → session report (with human-approved grades).

SDK: createVerticalWorkflow(VERTICAL_DEMO_SEEDS.edu) — attendance, polls, breakouts, grade suggest/approve.

Gates before “production”:

• Yjs whiteboard adapter + snapshot policy
• SFU port for multiparty media (no hard-coded vendor)
• Attendance + poll events persisted on Worker
• AI grading: rubric + provenance; no auto-publish without educator approve (implemented in workflow)
• FERPA/COPPA configurable retention/consent/export

Dashboard: /edu — interactive studio drives real SDK events.

FluxyHealth (preview)

Journey: Consent → care room → telehealth session → FHIR context → audit seal.

Compliance boundary: No “HIPAA compliant” marketing until BAA, risk assessment, and vendor chain are complete. Synthetic data only in UI.

FluxyEvent (beta demo)

Journey: Ticket verify → lobby → stage live → moderated Q&A → recap.

Reuse corrected Stream/poll primitives; ticket provider as adapter.

FluxyFinance (preview)

Journey: Market room → provider snapshot → risk alert → invoice approval → audit export.

No PAN storage; no auto-trade; “not financial advice” copy required.

Cross-Reality Continuity (prototype)

Journey: Capability handshake → checkpoint → handoff → viewport resolve → canonical cursor.

Simulator validates protocol without XR headset; WebXR lazy-loaded when available.

Console information architecture

Single console (no duplicate auth shells). Groups in console-nav.ts:

Each industry route: overview studio, readiness badges, link to /security and docs.

Follow-ups: command palette entries, breadcrumb labels, overview shortcuts to Industries (see backlog).

Landing & marketing

Narrative: “One room for chat and every realtime product.”

Implemented:

• Updated hero copy (lib/marketing-landing.ts)
• Product switcher in hero (landing-hero-client.tsx)
• #platform section — primitives, product suite, industry solutions with readiness chips (landing-platform-section.tsx)

Follow-ups: Hero mode animation (chat → classroom → event) with prefers-reduced-motion; structured data update; feature comparison rows for verticals.

Compliance & claim policy

Prioritized backlog

Done (this expansion pass)

• vertical-platform kernel + tests
• vertical-workflows + demo seeds + tests
• Interactive vertical studios wired to SDK + optional Worker sync
• Worker capability router — POST/GET /rooms/:id/capabilities/events, D1 persistence, idempotency, policy gates (capability-platform.js)
• SDK createCapabilityClient + syncWorkflowEventsToWorker
• Provider adapter ports (vertical-adapters.ts) + demo adapters
• Yjs collab port contract + snapshot policy (yjs-collab.ts); dashboard uses Yjs via yjs-provider.tsx
• FluxyIoT rule action execution + credential redaction from public device model
• Excalidraw whiteboard lazy-loaded; pnpm stub for @excalidraw/mermaid-to-excalidraw (build green; Mermaid paste disabled)
• Dashboard next build passes (Turbopack)
• PLATFORM_READINESS wired to landing #platform and console overview badges
• Console Operate nav group + command palette Industries/Labs/Operate sections
• Breadcrumbs show nav group (Build / Industries / Operate / …)
• Landing hero room mode strip (chat → classroom → event → game → devices) with reduced-motion
• SDK subpath exports: @fluxy-chat/sdk/edu, /health, /event, /finance, /continuity
• FluxyEdu SFU demo adapter panel + related console links on all vertical studios
• Console nav groups (Build / Products / Industries / Labs)
• Landing platform section + hero repositioning
• SDK tsc clean
• DB migration 0156_room_capability_events.sql
• Capability DO fan-out + WS capability_event
• Customer Memory Graph client (CDP + knowledge graph)
• Moderation Labels API + rule builder (SDK)
• Autonomous agent task bus (D1 0157 + REST)
• Digital Twin MCP tool registry

Next — foundation (remaining for production)

1. DO fan-out for capability events — Done: publishCapabilityEvent → fanoutRoomInternal + WS capability_event in Room DO

Platform expansion layer (July 2026)

Vertical production gates

IA & docs

• docs/guides/fluxy-edu-quickstart.md
• Overview page industry cards linking to /edu … /continuity
• ROADMAP §5.3 status table (link here)

Migration strategy

1. No breaking SDK renames for chat exports; vertical types added alongside.
2. Alias legacy exports where renamed (LlmProvider → AiProvider, etc.).
3. Route compatibility — existing /collab, /stream URLs unchanged.
4. Gradual Worker rollout — feature flag per workspace capability.
5. Deprecate custom CRDT for collaboration docs once Yjs path ships (document in CHANGELOG).

References (2026 best practice)

• Portal SDK — competitive patterns adopted: portal-sdk-comparison.md
• Yjs — CRDT docs + snapshot truncation (ADL aligned)
• SMART on FHIR — clinical context by reference, not payload embedding
• Cloudflare DO — single-room authority; fan-out for scale (ADL)
• Device shadow — desired vs reported; vector clock for conflicts (ADL)
• WCAG 2.2 — captions, keyboard, focus for Edu/Health surfaces

Document maintenance

Update this file when:

• A vertical moves readiness tier (prototype → beta → production).
• Worker persistence lands for a capability.
• Audit finds new P0/P1 issues.

Short link in ROADMAP.md §5.3 only — do not duplicate full content there.