# FlowMaster — Canvas

**Live at https://canvas.flow-master.ai** · operations cockpit for every process the company runs.

Canvas is the FlowMaster operator surface. Industrial-blueprint doctrine:
paper canvas, navy frame, amber accent, 1px hairlines, square edges,
monospace operational density. People, Finance, Procurement, and IT in
one frame.

## What it is

- React 19 single-page app (Vite + ReactFlow + cmdk + framer-motion +
  zustand + dagre + leaflet).
- Connected directly to EA2 in the browser via the API client at
  `src/lib/api.ts`. EA2 is the runtime source of truth.
- Microsoft SSO is the primary sign-in path. The login screen probes
  `/api/v1/auth/microsoft/login` on mount and only enables the SSO
  button when the redirect is wired; the dead-button state is honest
  ("not configured" / "not wired") instead of silently failing.
  Developer dev-login remains as a fallback for the demo lane.

## Scenes

- Landing — entry surface with persona switcher and recent processes.
- Mission Control — live work-items + reactflow process graph + inspector.
- Approvals — work waiting on the signed-in operator.
- Run History — recent runtime transactions and outcomes.
- Process Studio (Wizard) — the Process Creation Wizard, ported from
  dev.flow-master.ai. Intake → analyze → generate → validate → publish.
  Writes to EA2 at every step via `src/lib/wizardApi.ts`.
- Hubs (HR / Finance / Procurement / IT) — department lenses over the
  EA2 catalog. Each hub focuses Mission Control, surfaces hub-specific
  KPIs, and exposes the start-process actions the hub head can take.
- Geo Attendance — leaflet map (OpenStreetMap tiles) showing per-site
  attendance status from `src/lib/attendanceApi.ts`.
- Chat — internal employee ↔ manager messaging (`src/lib/chatApi.ts`),
  threaded, text-only. Replaces booting Teams for "what laptop?" type
  questions.
- Command Assistant (Agent) — chat surface with deterministic tools
  (`src/lib/agentTools.ts`) for navigation, process start, chat send,
  retain / recall against per-tenant memory. When the LLM proxy
  (`llm-proxy/`) is configured the assistant also synthesises fluent
  natural-language replies; when it isn't, the deterministic path
  still works.
- Documents — data shapes per process.
- Explainer — "What is FlowMaster?" recalled from the FlowMaster
  explainer and rendered in-product.
- Settings — identity, theme, polling cadence, console default.
- Login / SSO callback.

## Three view-as personas

Bundled in `src/data/personas.ts`. Switching persona re-signs in under
the persona's email so the operator UI reflects that seat.

| Persona | Title                | Default hub  |
|---------|----------------------|--------------|
| Mariana | Chief Executive      | Finance      |
| Aisha   | Head of People (HR)  | HR           |
| Rohan   | Head of IT           | IT           |

## Agent + per-tenant memory

`src/lib/agentMemory.ts` keeps three fact kinds (world / experience /
opinion) keyed by tenant + user. The agent calls deterministic tools
defined in `src/lib/agentTools.ts`. When `OPENAI_API_KEY` or
`ANTHROPIC_API_KEY` is set on the `llm-proxy/` sidecar, the agent layers
LLM responses on top of the tool output; otherwise it falls back to the
deterministic display strings.

The proxy lives in `llm-proxy/main.py` (FastAPI, no streaming, no tool
calls, no images). The shape mirrors `@earendil-works/pi-ai`'s
normalized completions so a forked Pi coding agent can drop in later
without changing the browser contract.

## Run, test, build

```bash
pnpm install

# dev (with backend proxy for live mode)
pnpm dev                                # → http://127.0.0.1:5173

# tests
pnpm test                               # vitest

# build
pnpm build                              # tsc + vite
```

## Deploy

Deployment is tracked in `FM06/flowmaster-ops`, overlay
`manifests/overlays/demo/`. nginx in the image reverse-proxies `/api/*`
to the EA2 backend so the SPA is same-origin (no CORS).

```bash
pnpm build
docker buildx build --platform linux/amd64 \
  -f Dockerfile.runtime \
  -t gitea.flow-master.ai/shad/canvas-frontend:sha-<git> \
  --load .
docker push gitea.flow-master.ai/shad/canvas-frontend:sha-<git>
# Then bump the image pin in manifests/overlays/demo/mc-deployment.yaml.
```

## Source

`gitea.flow-master.ai/shad/canvas-frontend` is the authoritative source
for canvas.flow-master.ai. The earlier `flowmaster-mission-control-demo`
repository is retained for history but no longer deployed.