Mission Control demo v2

Polished command-center for FlowMaster with two data modes: - SNAPSHOT: bundled src/scenarios.json from demo.flow-master.ai - LIVE: in-browser fetch via src/lib/api.ts (dev-login + bearer) Scenarios: - procurement, extra-1, extra-2 (live from EA2) - ar, hcm, gl, service (industry blueprints, same typed shell) Honesty pass after Oracle review: - No invented numbers (Telemetry derives SLA + agent acceptance from real data) - Preview-only actions fire toasts naming the endpoint to wire them - Blueprint tours framed as 'industry blueprint', not 'we don't have this yet' - Mode pill + last-fetch age + refresh in topbar - Dev CORS dodged via vite proxy; production deploys same-origin 18 vitest tests + 26 playwright smoke assertions + DOM layout audit. Constraint: cross-origin live mode rejected by browser → fall back to snapshot Rejected: hardcoded SLA % | dishonest demo metrics Directive: wire preview-only action handlers to /api/runtime/transactions/{id}/actions to ship them for real Confidence: high Scope-risk: narrow Not-tested: production deployment via flowmaster-ops overlay
2026-06-14 00:09:32 +04:00
commit 3ffd0e68a7
45 changed files with 15603 additions and 0 deletions
@@ -0,0 +1,152 @@
+# FlowMaster — Mission Control demo
+
+A polished, presenter-ready command-center for FlowMaster. Lives at
+[`shad/flowmaster-mission-control-demo`](https://gitea.flow-master.ai/shad/flowmaster-mission-control-demo)
+on Gitea.
+
+## What this is (and isn't)
+
+**Is:**
+
+- A single-page React 19 app (Vite + ReactFlow + cmdk + framer-motion + zustand
+  + dagre).
+- Polished command-center for any FlowMaster process: graph, queue, inspector,
+  tour, command palette, live-mode toggle, run history.
+- Two data modes:
+  - **SNAPSHOT** (default): bundled `src/scenarios.json`, captured from
+    `demo.flow-master.ai`. Fast, offline, deterministic.
+  - **LIVE**: in-browser fetch from the same backend via the API client at
+    `src/lib/api.ts` (dev-login → bearer → `/api/ea2/work-items` →
+    `/api/ea2/process-definitions/{k}/graph` → `/api/runtime/transactions/{id}`).
+    Loading and error states are wired through `src/scenes/MissionControl.tsx`.
+
+**Isn't:**
+
+- Not a replacement for the existing demo at https://demo.flow-master.ai
+  (Next.js fm-shell). This is a separate command-center experience.
+- Not multi-tenant. No auth UI, no tenancy switcher, no settings.
+- Not wired to actually mutate state. Every action button (start runtime,
+  dispatch agent, approve, decline, confirm) is **preview-only** and fires a
+  toast naming the endpoint that would make it real.
+
+## Scenarios in the catalog
+
+| id          | mode      | source                                                              |
+| ----------- | --------- | ------------------------------------------------------------------- |
+| procurement | live      | Purchase Requisition → PO (`pr_to_po_def` on demo.flow-master.ai)    |
+| extra-1     | live      | Atlas F1 Fresh (procurement variant)                                |
+| extra-2     | live      | Atlas F1 Fresh (procurement variant)                                |
+| ar          | blueprint | AR · Customer Refund Approval                                       |
+| hcm         | blueprint | HCM · New Hire Onboarding                                           |
+| gl          | blueprint | GL · Period-End Close                                               |
+| service     | blueprint | Service Ops · Customer Incident                                     |
+
+**Live** = backed by a real EA2 process definition currently in the demo
+backend, with real runtime transactions and a real work-item queue.
+
+**Blueprint** = hand-modelled in the same typed format. Identical UI surface;
+the backend just doesn't have a runnable definition for it yet. Internal
+metadata carries `isSynthetic: true` for provenance audits.
+
+## How honesty is enforced in this code
+
+This pass came out of an Oracle review that called out theatrical bits in the
+prior version. Safeguards now in place:
+
+- **No invented numbers.** `src/components/Telemetry.tsx` derives every value
+  from the active scenarios (`SLA = 1 - errored / cases`, agent acceptance =
+  fraction of agent runs not in `proposed`). The throughput sparkline plots
+  the actual `running` rollup over time, not a sine wave. The "ui tick" dot
+  is labelled as a UI heartbeat and tooltip-named as such.
+- **No fake buttons.** Every preview-only action fires a toast that names the
+  endpoint that would make it real, and carries a `preview` marker.
+- **No misleading tour copy.** Blueprint tours frame the scenario as an
+  industry blueprint, not "we don't have this yet".
+- **Mode is always visible.** Topbar has a `SNAPSHOT`/`LIVE` pill, last-fetch
+  age, and a refresh button when live.
+
+## Live-mode mechanics (the CORS gotcha)
+
+`demo.flow-master.ai` does not advertise CORS headers for arbitrary origins.
+
+- In **dev** (`pnpm dev`): Vite proxies `/api/*` to
+  `${VITE_FM_BASE:-https://demo.flow-master.ai}` (see `vite.config.ts`). The
+  browser sees a same-origin request, no CORS check. `src/lib/api.ts` uses an
+  empty `baseUrl` in dev for this.
+- In **production**: deploy the build at the same origin as the backend (or
+  behind a reverse proxy that passes `/api/*` through). Cross-origin
+  deployments fail gracefully — `setMode("live")` catches the error, surfaces
+  it in the topbar banner and a toast, and falls back to snapshot mode.
+
+## Run, test, build
+
+```bash
+pnpm install
+
+# refresh the bundled snapshot from demo.flow-master.ai
+pnpm fetch:scenarios
+
+# dev (with backend proxy for live mode)
+pnpm dev                                # → http://127.0.0.1:5173
+
+# tests
+pnpm test                               # vitest, 18 tests across api, live,
+                                        # synthetic, layout
+
+# build
+pnpm build                              # tsc + vite, single chunk ~225 KB gz
+
+# end-to-end smoke + screenshots
+pnpm qa:smoke                           # playwright headless, 26 assertions
+
+# DOM layout audit
+pnpm qa:layout
+```
+
+## File map
+
+```
+src/
+├── data/                    # ProcessScenario domain + snapshot + blueprint catalog
+├── lib/                     # API client + live-scenario builder (+ tests)
+├── state/store.ts           # zustand: scene, mode, scenario, tour, recents, toasts
+├── graph/layout.ts          # dagre LR auto-layout (+ tests)
+├── components/              # ProcessGraph, Inspector, LeftRail, CommandBar, Tour,
+│                            # Telemetry, Toaster, icons
+├── scenes/                  # Landing, MissionControl, RunHistory
+├── App.tsx                  # shell: topbar (mode pill / refresh / tour / ⌘K)
+├── index.css                # design system (~700 lines)
+├── main.tsx
+└── scenarios.json           # cached snapshot of demo.flow-master.ai
+
+qa/
+├── smoke.mjs                # Playwright e2e + 9 screenshots
+└── layout_audit.mjs         # programmatic clipping/overlap check
+
+vite.config.ts               # /api → demo.flow-master.ai proxy for dev
+fetch_scenarios.mjs          # Node script to refresh src/scenarios.json
+```
+
+## Deploy
+
+Production deployment is tracked in `FM06/flowmaster-ops` under
+`manifests/overlays/mc.flow-master.ai/`. A static nginx serves `dist/`;
+ingress fronts it at `mc.flow-master.ai`. `/api/*` is reverse-proxied to the
+same backend `demo.flow-master.ai` talks to — that's what makes live mode
+work in production without CORS.
+
+```bash
+pnpm build
+# dist/ is the static site → ship to nginx referenced by the ops overlay
+```
+
+## What's intentionally not here
+
+- Authentication UI (dev-login is used because this is a demo lane).
+- Mutation endpoints (every action is preview-only and the toast names the
+  endpoint).
+- Mobile layout (1440px-and-up demo surface).
+- Route persistence / deep linking (scene + scenario live in memory).
+- i18n (English only).
+
+Small, well-scoped follow-ups — not architectural changes.