web/docs/DATA_MODEL.md

A11oy — Data Model & API Contract

A11oy is a public, demo-grade artifact. Every visible surface is backed by a real HTTP endpoint on @workspace/api-server. No mock data, no GraphQL auth-walls.

Routes

All routes live under the /api/a11oy/ prefix and are exempt from globalAuthEnforcer via PUBLIC_PREFIXES in artifacts/api-server/src/middlewares/global-auth-enforcer.ts. Mutating routes self-enforce auth + CSRF at the route level (routes/doctrine-crud.ts).

Surface (frontend)	Endpoint	Source file
HomePage hero / metrics strip	GET /api/a11oy/dashboard	routes/a11oy-dashboard-api.ts (new)
NowPage live ticker	GET /api/a11oy/now	routes/a11oy-now-api.ts
Capability Fabric panels	GET /api/a11oy/fabric/*	routes/a11oy-fabric-api.ts
Doctrine V6 readouts	GET /api/a11oy/doctrine/*	routes/doctrine-api.ts
Doctrine CRUD (admin)	POST/PUT/DELETE /api/a11oy/doctrine/*	routes/doctrine-crud.ts (auth + CSRF)
GovernancePanels	GET /api/a11oy/fabric/proof-packets, /policy	routes/a11oy-fabric-api.ts (preserved)

GET /api/a11oy/dashboard

Returns AlloyDashboardStats aggregated from the alloy_* drizzle tables (alloyWorkflows, alloyWorkflowRuns, alloyApprovals, alloyAuditLog). Falls back to a zero-filled response when the tables are empty so the HomePage hero never renders nulls.

{
  "ok": true,
  "data": {
    "totalWorkflows": 0,
    "totalRuns": 0,
    "runningRuns": 0,
    "pendingApprovals": 0,
    "failedRuns": 0,
    "successRate": 100,
    "avgDurationMs": null,
    "workflowsByStatus": [],
    "recentActivity": []
  },
  "meta": {
    "timestamp": "2026-05-16T02:33:17.057Z",
    "source": "db",
    "visibility": "public",
    "doctrine": "V6"
  }
}

The frontend hook (useDashboardSnapshot in pages/HomePage.tsx) treats successRate as already-percent (0–100); the resolver converts the raw 0–1 ratio before returning.

Notes

• The legacy GraphQL alloyDashboard resolver (graphql/domains/alloy.ts) remains for parity but is no longer used by HomePage — it required a session and 401'd anonymous demo loads.
• GovernancePanels was already payload-grounded on /api/a11oy/fabric/proof-packets + /api/a11oy/fabric/policy and is preserved unchanged.