Ops/Admin AI Agent — Prototype Dashboard

A clickable prototype dashboard for a field-service "Ops/Admin AI Agent" (a field service management ops-coordination agent).

⚠️ This is a communication and alignment artifact, not a product. Its only job is to let the team look at one screen and agree on what the agent does, what it escalates, and how it reasons.

What this is (and isn't)

• No backend, no database, no auth, no persistence, no real API calls.
• Mocked data only — every data point is a hardcoded TypeScript object under src/data/. Invented values are commented PLACEHOLDER in the code.
• Local interactivity (e.g. resolving an escalation row) updates React state only and resets on reload. Nothing is saved anywhere.

Quick start

npm install   # first time only — install dependencies
npm run dev   # start the dev server, then Ctrl+Click the printed localhost URL

That's all you need day-to-day. Edit files, the browser hot-reloads, Ctrl+C in the terminal to stop. Nothing persists — a refresh resets all state.

Before pushing to git, run a build to confirm it type-checks cleanly:

npm run build   # type-check (tsc) + production build

Source of truth

The only authoritative source is the set of Mermaid diagrams in ./reference (uc1.mmd … uc9.mmd), one per use case. There is no written spec.

• Do not invent product behaviour beyond what the diagrams show.
• The diagrams are reference only — they are not rendered in the UI.
• Ambiguities / conflicts between diagrams are flagged in plan.md → Open Questions, not silently resolved.

See CLAUDE.md for the full guardrails and domain rules.

The four tabs (single-page app, tabs via component state — no router)

1. Today — metric cards (visits handled, confirmations sent, open escalations, POs pending) + a recent-activity strip.
2. Escalation Queue — the live "needs a human" list. Each row shows the source use-case chip, the issue, the agent's reasoning, who it is routed to, age, and action buttons. Filterable by use case. (Escalation is cross-cutting — it's the queue, not a use case.)
3. Decision Log (most important tab) — the agent's own judgment calls (channel, timing, selection, classification) each with reasoning, plus a channel-choice distribution bar.
4. Activity Feed — chronological agent actions across all nine use cases.

The nine use cases

UC	Name	Summary
UC1	Pre-Checks	APG checks (Access History, Permit Required, Guarding Required).
UC2	Appointment Confirmation	Channel resolution, quiet hours, response handling.
UC3	Dispatch	Shift-start, slippage/substitute, engineer-query router.
UC4	Parts Procurement	Supplier scoring, spend threshold, PO.
UC5	Hygiene Check	Five completion checks + monthly fail pattern.
UC6	Attendance & Training	Day classification vs engineer statement.
UC7	Onboarding/Offboarding	Onboarding, offboarding, site-audit cadence.
UC8	System Configuration	Scheduled alert-rule tick — escalates SLA / unallocated-engineer breaches.
UC9	No-Access	Engineer-side vs customer/site-side, call attempts.

Domain rules to remember (non-negotiable)

• Priority bands: Emergency Response, 4-hour Response, 8-hour Response, 24-hour Response (most → least urgent). Never use P1/P2/P3 labels.
• Logging convention: a Pass is logged as a count only; a Fail or escalation is logged with reasoning.
• Escalation routing targets: Human Ops Admin, Planner, Engineering Supervisor, Contract Manager, Procurement Manager. Fallback: if a role/tier isn't bought for the tenant, the escalation routes to the configured human owner of that role.
• Pod context: an Engineering Supervisor over roughly 10–13 engineers with skill sets (electrical, plumbing, multi-skilled).

Project layout

reference/        uc1.mmd … uc9.mmd  ← source-of-truth Mermaid diagrams (not rendered)
src/
  App.tsx           tab shell
  main.tsx          entry point
  types.ts          shared TypeScript types
  data/             all mocked data (engineers, escalations, decisions, channelStats, activity, metrics)
  components/       TabNav, TodayTab, EscalationQueueTab, DecisionLogTab, ActivityFeedTab, shared
CLAUDE.md         full guardrails, domain rules, brand tokens
plan.md           build plan + Open Questions

Stack

Vite + React + TypeScript + Tailwind. Icons via lucide-react, small charts via recharts.

Brand tokens (Tailwind theme colors)

• primary #213A54 (dark navy) — headers, primary surfaces, primary buttons.
• secondary #FFDA02 (yellow) — accent only (highlights, small badges).
• tertiary #0056B3 (blue) — links, info, secondary actions.
• neutral #3C434A (gray) — body text, borders, muted UI.