Handbook Architecture
Overview
The Handbook domain is a document product system, not a chat wrapper around PDFs. It turns policy sources, district handbook sources, indexed evidence, product workflows, and human review decisions into durable handbook outputs and review reports.
Source of truth for the product code is packages/domain-handbook/src/**.
There are two operator surfaces: the focused Handbook application under
apps/handbook-app/** and the broader Admin UI Handbook scope at
/admin/?dashboardScope=handbook.
Layer Model
Product logic belongs in modules, workflows, and the policy-review runner. UI handlers validate requests, start work, poll progress, and render stable projections.
Runtime Registration
loadHandbookArtifacts() registers the current Handbook runtime artifacts when the Handbook domain is enabled:
| Runtime surface | Count | Source |
|---|---|---|
| Agents | 7 | packages/domain-handbook/src/agents/index.ts |
| Workflows | 17 | packages/domain-handbook/src/loader.ts |
| Tools | 2 | packages/domain-handbook/src/tools/index.ts |
| MCP servers | 0 | packages/domain-handbook/src/loader.ts |
The runtime-generated route families are:
/handbook/routes.json/handbook/workflows/{workflowSlug}/handbook/workflows/{workflowSlug}/start-async/handbook/workflows/{workflowSlug}/create-run/handbook/workflows/{workflowSlug}/start/handbook/workflows/{workflowSlug}/runs/{runId}/handbook/tools/{toolSlug}/handbook/agents/{agentSlug}/generate/handbook/agents/{agentSlug}/stream
Use /handbook/routes.json in the active environment for exact slugs.
Admin Workbench Surfaces
Focused Handbook Application
apps/handbook-app is the focused end-user and reviewer application. Its
current UI routes include the checker/report flow, handbook library, district
registry, and an internal reviewable-source inspector. Its Express adapter
owns /api/compliance/**, /api/handbooks/**, /api/district-profiles/**,
/api/district-source-context, /api/generations/**, and development-only
reviewable-source artifact routes.
The focused app delegates product behavior to Handbook package modules and the policy-review runner. It must not be mistaken for a second implementation of policy logic.
Admin UI Workbench
The Admin UI Handbook scope includes these tabs:
| Tab | Purpose |
|---|---|
| Handbook Workbench | Work items, stages, gates, and evidence. |
| Corpus & Indexing | Source PDF, candidate corpus, verification, promotion, and cleanup. |
| RAG Tuning | Retrieval tests, grounded answers, citations, and audit. |
| Handbook Generation | Answer ledger, candidate review, promotion, rendered outputs, and reports. |
| Policy Review Flow | One-page review path for choosing/uploading a handbook, running review, seeing policy/checklist flags, and exporting. |
| Policy Review | Detailed queue for findings, evidence, reviewer state, saved runs, and feedback. |
| Artifacts / Run History | Artifacts, operations, audit records, promoted versions. |
| Services | Connected service health. |
| Build Info | Build, branch, environment, and feature gates. |
The dashboard calls browser paths under /api/admin/handbook/*; the Admin UI server rewrites them to the BFF mount. Local calls use /admin-api/admin/handbook/*; testing APIM calls use /dashboard/admin-api/admin/handbook/*.
Storage And Indexes
| Store | Current role |
|---|---|
[HANDBOOK].[RagWorkflowState] | Admin RAG preset/corpus state persistence. |
[HANDBOOK].[log_RagAuditRecords] | Retrieval, generation, verification, warning, and telemetry audit records. |
[HANDBOOK].[ProductWorkbenchMetadataRecords] | Product work-item and workflow metadata projections. |
[HANDBOOK].[SourceArtifactRecords] | Source and derived artifact metadata records. |
[HANDBOOK].[SourceArtifactIdempotencyKeys] | Source/derived artifact idempotency tracking. |
[HANDBOOK].[IndexedArtifactRegistry] | DB-backed ledger of indexed policy and handbook artifacts used by policy-review selectors and Azure AI Search filters. |
[HANDBOOK].[PolicyReviewJobs] | Async policy-review queue, attempts, progress, retry links, and stale-running recovery. |
[HANDBOOK].[PolicyReviewRuns] | Policy-review run records and report JSON. |
[HANDBOOK].[PolicyReviewFindings] | Queryable finding rows with status, severity, disposition, review state, and full finding JSON. |
[HANDBOOK].[PolicyReviewReviewerActions] | Reviewer action and quality-feedback ledger. |
[HANDBOOK].[PolicyReviewUsageEvents] | Per-stage policy-review search/model/export telemetry. |
Large source and derived bytes should live in Blob storage in deployed environments. SQL holds queryable state, projections, metadata, review state, and telemetry. Local filesystem and memory adapters remain for development and tests.
Source-Backed Boundaries
| Boundary | Source |
|---|---|
| Domain exports and manifest | packages/domain-handbook/src/index.ts |
| Runtime artifact loader | packages/domain-handbook/src/loader.ts |
| Agent descriptors | packages/domain-handbook/src/agents/** |
| Product tools | packages/domain-handbook/src/tools/** |
| Workflow runners and schemas | packages/domain-handbook/src/workflows/** |
| Ingestion profiles | packages/domain-handbook/src/ingestion-profiles/index.ts |
| Source artifacts | packages/domain-handbook/src/source-artifacts/index.ts |
| Policy-review runner | packages/domain-handbook/src/policy-review-run/** |
| Admin BFF route source | apps/admin-api/src/routes/admin/handbook-rag.ts |
| Browser DTO/client source | apps/admin-ui/src/api-client/handbook-rag.ts |
| Focused Handbook application | apps/handbook-app/src/App.tsx and apps/handbook-app/server/routes.ts |
| SQL schema | db/sqlproj/Mastra.Platform.HandbookDb/model/Tables/HANDBOOK.*.sql |
Design Rules
- MSBA policy is authoritative for policy review.
- Retrieval finds candidate evidence; it does not decide whether a handbook is correct.
- Missing policy evidence is unresolved review work, not proof of a handbook error.
- Policy-review source selection is DB-backed by
[HANDBOOK].[IndexedArtifactRegistry]; the Admin selector path does not silently fall back to local artifact scans. - Long-running work should expose durable refs, progress, diagnostics, and audit records.
- Report exports should be artifact refs; the UI should not treat rendered HTML/PDF as the only source of truth.
Related Pages
File preparation, profile ingestion, PDF job stages, Search indexes, and the indexed artifact registry
Functional workflow map from source intake through generation, review, promotion, and policy review
Runtime and Admin BFF endpoint families
Policy comparison, checklist pass, persistence, and UI results