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