MSBA Handbook
Overview
The MSBA Handbook domain owns PDF-first workflows for preparing handbook and policy sources, indexing them into Azure AI Search, generating grounded handbook answers, and reviewing handbooks against authoritative MSBA policy.
The implementation is package-owned under packages/domain-handbook/src/**.
The focused Handbook application lives under apps/handbook-app/**; the
broader operator workbench is exposed through the Admin UI Handbook scope,
especially:
/admin/?dashboardScope=handbook&dashboardTab=corpus-indexing/admin/?dashboardScope=handbook&dashboardTab=rag-tuning/admin/?dashboardScope=handbook&dashboardTab=handbook-generation/admin/?dashboardScope=handbook&dashboardTab=policy-review-flow/admin/?dashboardScope=handbook&dashboardTab=policy-review
What It Does
- Ingestion and indexing: prepares handbook PDFs and policy corpora as reviewable indexed artifacts.
- RAG tuning: manages candidate/active corpus bundles, active sources, answer probes, and promotion/rollback operations.
- Handbook generation: runs product workflows for source understanding, principal-answer extraction, generation, review, revision, render/export, adherence review, and comparison.
- Policy review: compares a selected handbook index against a selected MSBA policy set and separately verifies the versioned Student Handbook Checklist 2025 item by item.
- Operator review: presents findings, checklist flags, evidence, suggested wording, saved runs, reviewer actions, quality feedback, and exports in the Admin UI.
Source Map
| Surface | Source |
|---|---|
| Domain package | packages/domain-handbook/src/** |
| Handbook agents | packages/domain-handbook/src/agents/** |
| Product tools | packages/domain-handbook/src/tools/** |
| Product workflows | packages/domain-handbook/src/workflows/** |
| Policy-review runner and contracts | packages/domain-handbook/src/policy-review-run/** |
| Checklist fixture | packages/domain-handbook/src/checklists/student-handbook-checklist-2025.json |
| Admin BFF routes | apps/admin-api/src/routes/admin/handbook-rag.ts |
| Browser API client | apps/admin-ui/src/api-client/handbook-rag.ts |
| Admin UI pages | apps/admin-ui/src/pages/dashboard/handbook-*.tsx |
| Focused Handbook application | apps/handbook-app/src/** and apps/handbook-app/server/** |
| Admin BFF OpenAPI | packages/admin-contracts/openapi.yaml |
| Handbook SQL model | db/sqlproj/Mastra.Platform.HandbookDb/model/Tables/HANDBOOK.*.sql |
Runtime Shape
Handbook exposes two complementary route families:
- Runtime/domain routes under
/handbook/*for generated workflow, tool, agent, and discovery routes. - Admin UI BFF routes under
/admin-api/admin/handbook/*locally, and/dashboard/admin-api/admin/handbook/*in testing through APIM/dashboard routing.
The focused Handbook application adds its own /api/* adapter surface for
compliance runs, handbook library/review, district profiles and source context,
reviewer context/remediation actions, and generated artifacts. Those routes
are owned by apps/handbook-app/server/routes.ts, not by the runtime's generic
domain-route generator.
The policy-review source selection is DB-backed. Selectable policy sets and handbooks come from [HANDBOOK].[IndexedArtifactRegistry], which stores the Azure AI Search index and filter metadata used by review runs.
Next Steps
How the Admin UI, BFF, runtime routes, workflows, agents, SQL, Blob storage, and Search indexes fit together
How uploaded PDFs become searchable, registry-backed policy and handbook artifacts
Functional workflow map from source intake through generation, review, promotion, and policy review
Runtime and Admin BFF route families for Handbook RAG, PDF preparation, and policy review
Product, source-context, policy-review, checklist, remediation, and evidence-synthesis agents
End-to-end policy review pipeline, checklist pass, persistence, and result semantics
Admin UI tabs and BFF behavior shared across Handbook workbench flows