# mastra-ai/mastra architecture

> Architecture diagram of the GitHub repository mastra-ai/mastra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mastra-ai/mastra
- Repository: https://github.com/mastra-ai/mastra

## Overview

Mastra is a TypeScript framework for building and operating AI applications. Developers define agents for open-ended tasks or workflows for explicit multi-step control; agents can use models and tools, with context and memory supporting execution. Human approval and persisted state allow suspended work to resume. Applications expose capabilities through server and MCP integrations, while SDKs and UI packages connect clients. The README documents evaluation and observability for production refinement. Runtime wiring beyond the sampled excerpts is represented only where the README establishes the capability; the excerpts do not establish detailed call paths.

Main entry points: [`packages/core/src`](https://github.com/mastra-ai/mastra/tree/main/packages/core/src) (Agents), [`packages/server/src`](https://github.com/mastra-ai/mastra/tree/main/packages/server/src) (Server endpoints), [`packages/core/src/agent-controller/session-run-engine.ts`](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/agent-controller/session-run-engine.ts) (Human approval), [`packages/core/src/workspace/search/search-engine.ts`](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/workspace/search/search-engine.ts) (Workspace search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["AI Runtime"]
  node_agent["Agents"]
  node_workflow["Workflows"]
  node_modelrouter["Model routing"]
  node_tools["Tools"]
  node_approval["Human approval"]
end

subgraph group_context["Context and State"]
  node_contextmgmt["Context and memory"]
  node_search["Workspace search<br/>[search-engine.ts]"]
  node_storage[("Execution storage")]
end

subgraph group_interfaces["App Interfaces"]
  node_mcp["MCP servers"]
  node_server["Server endpoints"]
  node_clients["Client SDKs"]
  node_react["React integration"]
  node_aiui["AI SDK integration"]
  node_deploy["Deployment"]
end

subgraph group_operations["Production Operations"]
  node_evals["Evaluations"]
  node_observability["Observability<br/>[context-storage.ts]"]
end

node_developer(("Application developer"))
node_user(("End user"))
node_provider(("Model providers"))
node_datasources(("Data sources"))

node_developer -->|"defines"| node_agent
node_developer -->|"defines"| node_workflow
node_agent -->|"requests inference"| node_modelrouter
node_agent -->|"invokes tools"| node_tools
node_workflow -->|"orchestrates"| node_agent
node_workflow -->|"runs steps"| node_tools
node_modelrouter -->|"routes requests"| node_provider
node_agent -->|"uses context"| node_contextmgmt
node_contextmgmt -->|"retrieves content"| node_search
node_contextmgmt -->|"persists state"| node_storage
node_workflow -->|"persists execution"| node_storage
node_agent -->|"suspends for approval"| node_approval
node_workflow -->|"suspends for approval"| node_approval
node_approval -->|"resumes state"| node_storage
node_developer -->|"exposes resources"| node_mcp
node_mcp -->|"serves agent capabilities"| node_agent
node_server -->|"exposes runtime"| node_agent
node_server -->|"exposes runtime"| node_workflow
node_user -->|"sends requests"| node_server
node_clients -->|"calls endpoints"| node_server
node_react -->|"uses SDK"| node_clients
node_aiui -->|"connects UI"| node_server
node_server -->|"runs on"| node_deploy
node_agent -->|"evaluated by"| node_evals
node_workflow -->|"evaluated by"| node_evals
node_agent -->|"traced by"| node_observability
node_workflow -->|"traced by"| node_observability
node_search -.->|"indexes content"| node_datasources

click node_agent "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_workflow "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_modelrouter "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_tools "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_mcp "https://github.com/mastra-ai/mastra/tree/main/packages/mcp/src"
click node_contextmgmt "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_search "https://github.com/mastra-ai/mastra/blob/main/packages/core/src/workspace/search/search-engine.ts"
click node_storage "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_approval "https://github.com/mastra-ai/mastra/blob/main/packages/core/src/agent-controller/session-run-engine.ts"
click node_server "https://github.com/mastra-ai/mastra/tree/main/packages/server/src"
click node_clients "https://github.com/mastra-ai/mastra/tree/main/client-sdks/client-js/src"
click node_react "https://github.com/mastra-ai/mastra/tree/main/client-sdks/react/src"
click node_aiui "https://github.com/mastra-ai/mastra/tree/main/client-sdks/ai-sdk/src"
click node_deploy "https://github.com/mastra-ai/mastra/tree/main/deployers"
click node_evals "https://github.com/mastra-ai/mastra/tree/main/packages/core/src"
click node_observability "https://github.com/mastra-ai/mastra/blob/main/packages/core/src/observability/context-storage.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_workflow,node_modelrouter,node_tools,node_approval,node_user toneBlue
class node_contextmgmt,node_search,node_storage toneAmber
class node_mcp,node_server,node_clients,node_react,node_aiui,node_deploy toneMint
class node_evals,node_observability toneRose
class node_developer,node_provider,node_datasources toneIndigo
```

## Components

### AI Runtime

- [Agents](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Workflows](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Model routing](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Tools](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Human approval](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/agent-controller/session-run-engine.ts): `packages/core/src/agent-controller/session-run-engine.ts`

### Context and State

- [Context and memory](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Workspace search](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/workspace/search/search-engine.ts): `packages/core/src/workspace/search/search-engine.ts`
- [Execution storage](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`

### App Interfaces

- [MCP servers](https://github.com/mastra-ai/mastra/tree/main/packages/mcp/src): `packages/mcp/src`
- [Server endpoints](https://github.com/mastra-ai/mastra/tree/main/packages/server/src): `packages/server/src`
- [Client SDKs](https://github.com/mastra-ai/mastra/tree/main/client-sdks/client-js/src): `client-sdks/client-js/src`
- [React integration](https://github.com/mastra-ai/mastra/tree/main/client-sdks/react/src): `client-sdks/react/src`
- [AI SDK integration](https://github.com/mastra-ai/mastra/tree/main/client-sdks/ai-sdk/src): `client-sdks/ai-sdk/src`
- [Deployment](https://github.com/mastra-ai/mastra/tree/main/deployers): `deployers`

### Production Operations

- [Evaluations](https://github.com/mastra-ai/mastra/tree/main/packages/core/src): `packages/core/src`
- [Observability](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/observability/context-storage.ts): `packages/core/src/observability/context-storage.ts`

### Other components

- **Application developer**
- **End user**
- **Model providers**
- **Data sources**

## Connections

- Application developer → Agents: defines
- Application developer → Workflows: defines
- Agents → Model routing: requests inference
- Agents → Tools: invokes tools
- Workflows → Agents: orchestrates
- Workflows → Tools: runs steps
- Model routing → Model providers: routes requests
- Agents → Context and memory: uses context
- Context and memory → Workspace search: retrieves content
- Context and memory → Execution storage: persists state
- Workflows → Execution storage: persists execution
- Agents → Human approval: suspends for approval
- Workflows → Human approval: suspends for approval
- Human approval → Execution storage: resumes state
- Application developer → MCP servers: exposes resources
- MCP servers → Agents: serves agent capabilities
- Server endpoints → Agents: exposes runtime
- Server endpoints → Workflows: exposes runtime
- End user → Server endpoints: sends requests
- Client SDKs → Server endpoints: calls endpoints
- React integration → Client SDKs: uses SDK
- AI SDK integration → Server endpoints: connects UI
- Server endpoints → Deployment: runs on
- Agents → Evaluations: evaluated by
- Workflows → Evaluations: evaluated by
- Agents → Observability: traced by
- Workflows → Observability: traced by
- Workspace search → Data sources: indexes content
