Admin Dashboard

Overview

The Admin Dashboard is the React/Express application in apps/admin-ui. It is the operator UI for runtime configuration, prompt workbench, model and agent management, SDAC prompt tuning, widget testing, content safety, Handbook RAG, Flow Map, changelog, and service health.

In APIM-backed testing environments, the supported browser entrypoint is:

https://test-aitools-llfc-apim.azure-api.net/dashboard/admin/

For Replit/local UI work, run the Admin UI locally and proxy API calls to the testing APIM route:

APIM_GATEWAY_URL=https://test-aitools-llfc-apim.azure-api.net
APIM_SUBSCRIPTION_KEY=<testing APIM subscription key>
MASTRA_APIM_SUBSCRIPTION_KEY=${APIM_SUBSCRIPTION_KEY}
MASTRA_RUNTIME_URL=https://test-aitools-llfc-apim.azure-api.net/dashboard/admin-api
VITE_MOCK_API=false
BASE_PATH=/admin/
PORT=8787
npm --prefix apps/admin-ui run dev

For layout-only work, use mock mode:

VITE_MOCK_API=true
BASE_PATH=/admin/
PORT=8787
npm --prefix apps/admin-ui run dev

Browser Routes

Source: apps/admin-ui/src/App.tsx.

Route	Purpose
/	Main scoped dashboard.
/handbook	Redirects to /?dashboardScope=handbook.
/prompt-workbench	Full prompt workbench route.
/evaluation-runs	Evaluation run list/detail surface.
/widget-testing	SDAC widget testing workflow.
/widget-embed-host	Widget iframe host used by tool sessions.
/mastra-studio	Embedded Mastra Studio launcher.
/internal-docs	Embedded internal docs.
/grafana	Embedded Grafana view when enabled.
/flow-map	Flow Map browser.
/changelog	Scope-aware changelog page.

Dashboard scopes are source-defined in apps/admin-ui/src/pages/dashboard/dashboard-profile.ts:

• core
• sdac
• k12
• tap
• handbook

Feature flags/build info control optional tabs such as Documentation, Grafana, Seed Agents, SDAC Prompt Tuning, Widget Testing, TAP Vector DB, Content Safety, Linear, Services, and Build Info.

API Routing Model

The browser calls same-origin /admin-api/* routes. Generated clients that start with /api/* are rewritten to /admin-api/* by apps/admin-ui/src/api-client/admin-auth.ts.

Local Vite live mode proxies /admin-api/* to MASTRA_RUNTIME_URL and strips the /admin-api prefix. In the recommended Replit live mode, MASTRA_RUNTIME_URL is the APIM dashboard admin API prefix:

https://test-aitools-llfc-apim.azure-api.net/dashboard/admin-api

The deployed dashboard Express server mounts:

Path	Source	Purpose
/health	apps/admin-api/src/app.ts	App Service/dashboard health probe.
/admin	apps/admin-api/src/app.ts	Static React app.
/admin-api	apps/admin-api/src/routes/admin/index.ts	Admin UI BFF routes.
/	apps/admin-api/src/app.ts	Redirects to /admin/.

BFF Route Groups

Source: apps/admin-api/src/routes/admin/index.ts.

Group	Route examples	Mutation class
Build info	/admin/build-info	read-only
Feature flags	/admin/feature-flags, /admin/feature-flags/:flagKey	read-only/admin mutation
Models	/admin/model-capabilities*, /admin/llm-params*	admin mutation
Agents	/admin/agent-profiles*	admin mutation
Prompt workbench	/admin/prompt-workbench/*	testing-safe/admin mutation; includes SSE
Evaluations	/admin/evaluation-runs*	testing-safe mutation
SDAC prompt tuning	/admin/sdac/feedback/*, /admin/sdac/tune-prompt*	testing-safe/admin mutation
Widget testing	/admin/widget-token, /sdac/widget-token, /admin/tools/widget-testing/session	testing-safe mutation
Services	/admin/services/health, /admin/health/detailed	read-only
Tool sessions	/admin/tools/*/session	testing-safe mutation
Content safety	/admin/content-safety/analyze	testing-safe/provider call
Handbook RAG and policy review	/admin/handbook/**	mixed; cleanup/reset/rollback/promote/retire are destructive/admin; policy-review run/retry/resume are long-running review mutations
Flow map	/admin/flow-map/*	read-only
Linear	/admin/linear/status, /admin/linear/verify	read-only/status verification
Changelog	/admin/changelog?scope=	read-only

See docs/internal/documentation-revival/endpoint-catalog.md for the broader route safety catalog.

Handbook Policy Review

The Handbook dashboard includes a one-page policy-review flow at:

/admin/?dashboardScope=handbook&dashboardTab=policy-review-flow

That flow lets reviewers choose a DB-registered MSBA policy set and indexed handbook, upload/prepare a handbook PDF, start an async review, watch progress, inspect policy findings, inspect checklist flags, record reviewer actions and quality feedback, and export the report. The detailed findings queue remains available at dashboardTab=policy-review.

Source-backed BFF routes after the /admin-api mount are:

Method	Path	Purpose
GET	/admin/handbook/policy-review	Dashboard projection with artifact options, selected sources, active job, saved runs, run detail, findings, checklist review, usage summary, and diagnostics.
POST	/admin/handbook/policy-review/run	Start a review for selected policy/handbook artifacts.
POST	/admin/handbook/policy-review/retry	Retry a failed review job.
POST	/admin/handbook/policy-review/resume	Resume/view a saved review run by runId.
POST	/admin/handbook/policy-review/findings/:findingId/actions	Record reviewer workflow action.
POST	/admin/handbook/policy-review/findings/:findingId/feedback	Record evidence, reasoning, and outcome quality feedback.
POST	/admin/handbook/rag-presets/pdf-jobs	Prepare uploaded PDFs for RAG or Review Flow; send preparationMode: "reviewable-unit-v2" or policyReviewPreparation: true for policy review.

The same run now includes the MSBA Student Handbook Checklist 2025 pass. The checklist result is exposed on runDetail.checklistReview, including expected/evaluated item counts, satisfied/missing counts, warning count, coverage score, checklist score, and item-level evidence refs where available.

Authentication

The current APIM/dashboard model has three distinct boundaries:

1. Browser to dashboard: use the APIM dashboard route.
2. Browser to /admin-api/*: include Ocp-Apim-Subscription-Key.
3. Dashboard/APIM to runtime /admin/*: APIM/dashboard forwards the upstream admin proxy secret; browser code should not call runtime /admin/* directly.

The Admin UI accepts subscription-key and subscription_key URL parameters and persists the key in browser session storage for same-origin API calls.

Runtime /admin/* routes are protected by packages/platform-runtime/src/server/routes/shared/admin-proxy-guard.ts when APIM or an admin proxy secret is configured. That guard only wraps /admin/*; routes such as /docs/chat, /health, /setup/db*, generic tool execution, and domain routes have separate route/deployment policies.

The dashboard widget-testing flow can mint widget tokens server-side. Replit should use that flow instead of receiving widget OAuth client credentials.

Replit Guidance

• Use mock mode for visual layout and interaction polish.
• Use live APIM mode for screens that depend on deployed feature flags, service health, widget token/session generation, prompt workbench runs, or real BFF responses.
• Do not provide full backend .env files to shared Replit workspaces.
• Do not call routes labeled destructive or never call from Replit in the endpoint catalog.
• Send backend/API/infra/database gaps back to the normal engineering workflow.

Source Code

Path	Description
apps/admin-ui/src/App.tsx	Browser route table.
apps/admin-ui/src/pages/dashboard/dashboard-profile.ts	Scopes, tabs, and feature-gated IA.
apps/admin-ui/src/api-client/admin-auth.ts	APIM key persistence and /api to /admin-api rewriting.
apps/admin-ui/src/api-client/custom-fetch.ts	Generated client fetch adapter.
apps/admin-ui/vite.config.ts	Mock/live mode and local proxy behavior.
apps/admin-api/src/app.ts	Express app routes and static shell.
apps/admin-api/src/auth/admin-access-context.ts	Dashboard entrypoint/auth and runtime header resolution.
apps/admin-api/src/lib/proxy.ts	Runtime proxy, SSE proxy, download proxy, and mock fallback helpers.
apps/admin-api/src/routes/admin/**	Admin UI BFF modules.
packages/platform-runtime/src/server/routes/index.ts	Runtime admin route aggregate.
packages/platform-runtime/src/server/routes/shared/admin-proxy-guard.ts	Runtime admin proxy guard.

Validation

Recommended local checks after Admin UI docs or API contract changes:

npm --prefix apps/admin-ui run typecheck
npm --prefix apps/admin-ui run build
npm --prefix apps/admin-ui run test:e2e

For deployed smoke, use APIM /dashboard/admin/ and at least one read-only /dashboard/admin-api/* request with the testing APIM subscription key.