Base Platform
Base Platform Overview
The shared platform is package-first but transitional. Runtime consumers import
stable surfaces from @maf/platform-runtime/*, @maf/platform-data,
@maf/platform-core, and @maf/platform-rag; some platform-runtime exports
deliberately bridge implementations that still live under src/mastra/**.
Package boundaries
| Package | Current responsibility |
|---|---|
@maf/platform-core | Stable domain and package-boundary types. |
@maf/platform-data | Shared SQL Server/Azure SQL client and lazy loader. |
@maf/platform-runtime | Agent factories, providers, routes, services, schemas, startup, storage, telemetry, tools, and shared workflows. |
@maf/platform-rag | Reusable ingestion, chunking, embedding, retrieval, generation, verification, evaluation, and audit pipeline. |
@maf/platform-config | Scaffold only; active runtime configuration still comes through platform-runtime config exports. |
Domain packages must not import one another or application code. Cross-domain behavior belongs in an appropriate platform package.
Runtime composition
apps/runtime/src/mastra-runtime.ts owns the running process. It initializes
configuration, storage, providers, shared dependencies, active domain loaders,
base/admin tools, routes, memory, workspace, scheduler, and observability.
runtime-entry/index.ts is only the Mastra CLI adapter.
MASTRA_TARGET selects k12, sdac, tap, handbook, or all. Core, admin,
and docs loaders are cross-cutting; optional artifacts still respect their skip
or opt-in flags.
Shared capabilities
Agent platform
The shared factory reads versioned Core.AgentProfiles, resolves models against
Core capability/parameter data, applies supported overrides, and caches by the
effective profile hash. See Unified Agent Platform.
Providers and services
- Azure AI Inference and Azure AI Foundry model providers.
- Provider-agnostic LLM selection and parameter normalization.
- Azure Content Safety for text/image moderation.
- Embedding generation and optional Cosmos vector search.
- Tavily structured web search and Perplexity synthesized web research.
- Shared SQL services, runtime storage, telemetry, timing, and health probes.
Managed identity and API-key modes are provider/deployment specific. Do not describe every Azure-hosted model as using one transport or authentication mode.
Base tools
Every target registers Tavily, Perplexity, single/batch embedding tools. TAP and
all also register Cosmos vector search. K12, TAP, and all register Azure
Content Safety. Registry keys and the embedded Mastra tool ID can differ for
compatibility; generated contracts record the executable tool ID.
See Shared Platform Tools for the exact current matrix.
Data ownership
The deployed Core schema includes versioned agent profiles, model capabilities,
LLM parameter sets, feature flags, deployment/resource metadata, and related
audit state. SQL project files under db/sqlproj/** are the deployment source;
runtime ensureTable() helpers are compatibility guards, not a replacement for
DACPAC deployment.
Configuration principles
- Use the parsed environment object from
@maf/platform-runtime/config/envat composition boundaries. - Use
@maf/platform-data/sqlserver-clientrather than creating domain-specific connection pools. - Keep descriptor defaults complete so agents can start when profile reads fail.
- Keep secrets in deployment configuration; never put them in docs examples, Bruno environments, or browser bundles.
- Treat
packages/platform-configas reserved until source moves there.
Verification
npm run lint:boundaries
npm run typecheck:packages
npm run test:agents
npm run test:contracts
npm run contracts:check
npm run contracts:bruno
For broad package/export work, run npm run verify:monorepo; for loader or
runtime changes, run the applicable target build or
npm run verify:runtime-smoke.