Skip to main content

Architecture & Docs Overview

Purpose​

This page is the hosted entry point to the repository architecture. The codebase is a transitional monorepo: application processes live in apps/**, reusable runtime and domain ownership is moving into packages/**, and selected shared implementations remain under src/mastra/**. Source and tests win when a page disagrees with implementation.

System shape​

Executable applications​

PathDeployed process
apps/runtime + runtime-entryMastra HTTP runtime and build/dev adapter. Runtime composition is owned by apps/runtime/src/mastra-runtime.ts.
apps/admin-uiReact operator dashboard and Express BFF. Browser traffic uses /admin-api/**; the BFF proxies controlled requests to runtime /admin/**.
apps/widgetSDAC assistant UI and BFF. It proxies /api/ingestion/** and /api/mastra/**.
apps/ingestion-serverFastAPI ingestion API plus independently registered Azure Functions v2 blueprints.
apps/handbook-appHandbook review/generation UI and Express server.
apps/health-aggregatorAzure Functions timer app for health aggregation, APIM keep-warm, and retention work.
apps/diagnostics-serviceRead-only diagnostics control-plane or worker service, including the diagnostics MCP HTTP handler.
apps/admin-ui-referenceLegacy static reference app; it is not the production dashboard.

The root npm workspaces are runtime-entry, apps/runtime, apps/diagnostics-service, and packages/*. The other apps retain independent install/build contracts.

Package boundaries​

Domain ownership lives in packages/domain-k12, packages/domain-sdac, packages/domain-tap, and packages/domain-handbook. Each domain supplies a loader that contributes agents, tools, workflows, routes, and MCP servers to runtime composition. Domain packages must not import one another or app code.

Shared ownership is divided across:

  • packages/platform-runtime: runtime factories, providers, routes, services, schemas, configuration, tools, telemetry, and explicit bridges to retained src/mastra/** implementations;
  • packages/platform-rag: reusable ingestion, retrieval, generation, verification, and evaluation contracts used by Handbook;
  • packages/platform-data: shared SQL Server/Azure SQL client;
  • packages/platform-core: stable domain/package type vocabulary;
  • packages/platform-config: reserved scaffold, not the current configuration owner;
  • packages/diagnostics-*: diagnostics contracts, gateway, and MCP clients.

Use package exports such as @maf/platform-runtime/* rather than reaching into bridged src/mastra/** files from new package or app code.

Runtime composition​

  1. scripts/build/generate-domain-barrel.ts resolves the active target and cross-cutting loaders.
  2. apps/runtime/src/mastra-runtime.ts configures dependencies and invokes the selected loaders.
  3. Registries are merged with duplicate detection, then route factories expose the selected agents, tools, and workflows.
  4. runtime-entry/index.ts constructs the final Mastra instance.
  5. Production builds copy domain bundles into .mastra/output/domain-runtimes/**; built execution does not evaluate raw domain TypeScript.

Data and contracts​

  • db/sqlproj/** is the authoritative DACPAC source for Core, K12, SDAC, TAP, Handbook, Ingestion, Reasoning, Recovered, Memory, and Mastra-native schemas.
  • docs/contracts/*.json and docs/openapi/*.json are generated or maintained API inventories; run their freshness checks before treating them as current.
  • bruno/** contains executable HTTP examples and smoke collections.
  • environments/**, .github/config/projects/**, and azure_template/profiles/** jointly define deployable environment behavior.

Change routing​

ChangeInspect together
Runtime/domain inclusionapps/runtime, domain loader/exports, generated barrels, build scripts, Dockerfiles, smoke tests
Agent/tool/workflowOwning package, registry/loader, conformance tests, contracts, Bruno, profile seeds
Public route/schemaRoute source, OpenAPI/contracts, Bruno request, route tests, hosted API page
DatabaseOwning SQL project, Mastra.AllDb, migration/seed needs, infra tests, deployment order
Deployment.github/workflows, .github/config, scripts/github-actions, azure_template, environments, Dockerfiles, db, tests/infra

Next pages​