# overmind-core/overmind architecture

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

- Interactive diagram: https://gitdiagram.com/overmind-core/overmind
- Repository: https://github.com/overmind-core/overmind

## Overview

Overmind is a platform for continuously improving specialized agents from production traces or other datasets. Users connect an agent, collect and organize data, define capability-level evaluations, run optimization or fine-tuning, then benchmark and serve models. The Console is one entry point; the REST API and MCP server expose platform workflows too. The README documents the product stages and capabilities, while sampled source confirms selected MCP, inference, and training internals; unsampled subsystems are represented at their documented directory level, with relationships limited to documented flows.

Main entry points: [`overbae/modal/modal_vllm_worker.py`](https://github.com/overmind-core/overmind/blob/main/overbae/modal/modal_vllm_worker.py) (vLLM serving), [`overbae/services/mcp/server.py`](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/server.py) (MCP server), [`overbae/services/mcp/catalog.py`](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/catalog.py) (MCP tool catalog), [`overbae/services`](https://github.com/overmind-core/overmind/tree/main/overbae/services) (Evaluation workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Console"]
  node_console_ui["Web console"]
end

subgraph group_data["Agent data"]
  node_capabilities["Capability graph<br/>[capabilities.py]"]
  node_traces["Trace observability<br/>[traces.py]"]
  node_datasets["Datasets<br/>[datasets.py]"]
end

subgraph group_improve["Evaluation and improvement"]
  node_eval_models[("Evaluation records<br/>[evaluation.py]")]
  node_eval_workflows["Evaluation workflows"]
  node_optimizer["Optimizer experiments<br/>[optimizer.py]"]
end

subgraph group_models["Model lifecycle"]
  node_finetuning_models[("Fine-tuning jobs<br/>[finetuning.py]")]
  node_training["SFT training<br/>[engine_unsloth.py]"]
  node_model_families["Model families<br/>[spec.py]"]
  node_model_registry["Model registry<br/>[model_registry.py]"]
  node_deployment["Deployment orchestration<br/>[deployment.py]"]
  node_deploy_reconcile["Deployment reconciler"]
  node_inference_client["Inference client"]
  node_inference_worker["vLLM serving"]
  node_context_budget["Context budgeting<br/>[context_budget.py]"]
  node_stack_config["Train/serve stacks<br/>[stacks.py]"]
  node_modal["Modal workers"]
  node_trained_weights[("Model weights")]
end

subgraph group_access["API and integrations"]
  node_iam[("Projects and identity<br/>[iam.py]")]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_mcp_catalog["MCP tool catalog<br/>[catalog.py]"]
  node_mcp_resources["MCP resources<br/>[resources.py]"]
  node_mcp_eval_tools["Evaluation tools"]
  node_mcp_train_tools["Fine-tuning tools"]
  node_mcp_connector_tools["Connector tools"]
  node_mcp_oauth["MCP OAuth<br/>[oauth_routes.py]"]
  node_api["REST API"]
end

node_user(("Agent builder"))
node_production_agent(("Instrumented agent"))
node_mcp_client(("Coding agent"))
node_inference_api["OpenAI-compatible API"]

node_user -->|"uses"| node_console_ui
node_console_ui -.->|"manages platform"| node_api
node_production_agent -->|"emits traces"| node_traces
node_traces -->|"forms datasets"| node_datasets
node_user -->|"scans repository"| node_capabilities
node_datasets -->|"evaluates"| node_eval_workflows
node_capabilities -->|"defines metrics"| node_eval_workflows
node_eval_workflows -.->|"records results"| node_eval_models
node_eval_workflows -->|"scores experiments"| node_optimizer
node_optimizer -->|"returns git diff"| node_user
node_datasets -->|"trains on data"| node_finetuning_models
node_finetuning_models -.->|"runs fine-tuning"| node_training
node_training -->|"resolves family"| node_model_families
node_training -.->|"produces weights"| node_trained_weights
node_model_families -->|"selects stack"| node_stack_config
node_deploy_reconcile -->|"reconciles deployments"| node_deployment
node_deployment -->|"deploys models"| node_modal
node_inference_client -->|"sends routed requests"| node_inference_worker
node_inference_worker -->|"reserves output tokens"| node_context_budget
node_inference_worker -->|"resolves family"| node_model_families
node_inference_worker -.->|"loads weights"| node_trained_weights
node_inference_worker -->|"serves inference"| node_inference_api
node_user -->|"connects coding agent"| node_mcp_client
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_catalog
node_mcp_server -->|"lists resources"| node_mcp_resources
node_mcp_catalog -->|"registers tools"| node_mcp_eval_tools
node_mcp_catalog -->|"registers tools"| node_mcp_train_tools
node_mcp_catalog -->|"registers tools"| node_mcp_connector_tools
node_mcp_server -->|"authenticates clients"| node_mcp_oauth
node_mcp_client -->|"uses REST API"| node_api

click node_console_ui "https://github.com/overmind-core/overmind/tree/main/frontend/src"
click node_capabilities "https://github.com/overmind-core/overmind/blob/main/overbae/models/capabilities.py"
click node_traces "https://github.com/overmind-core/overmind/blob/main/overbae/models/traces.py"
click node_datasets "https://github.com/overmind-core/overmind/blob/main/overbae/api/datasets.py"
click node_eval_models "https://github.com/overmind-core/overmind/blob/main/overbae/models/evaluation.py"
click node_eval_workflows "https://github.com/overmind-core/overmind/tree/main/overbae/services"
click node_optimizer "https://github.com/overmind-core/overmind/blob/main/overbae/models/optimizer.py"
click node_finetuning_models "https://github.com/overmind-core/overmind/blob/main/overbae/models/finetuning.py"
click node_training "https://github.com/overmind-core/overmind/blob/main/overbae/services/sft_assets/engine_unsloth.py"
click node_model_families "https://github.com/overmind-core/overmind/blob/main/modal_shared/modelfam/spec.py"
click node_model_registry "https://github.com/overmind-core/overmind/blob/main/overbae/core/model_registry.py"
click node_deployment "https://github.com/overmind-core/overmind/blob/main/overbae/services/deployment.py"
click node_deploy_reconcile "https://github.com/overmind-core/overmind/blob/main/overbae/tasks/inference_controller.py"
click node_inference_client "https://github.com/overmind-core/overmind/blob/main/overbae/services/inference_client.py"
click node_inference_worker "https://github.com/overmind-core/overmind/blob/main/overbae/modal/modal_vllm_worker.py"
click node_context_budget "https://github.com/overmind-core/overmind/blob/main/modal_shared/context_budget.py"
click node_stack_config "https://github.com/overmind-core/overmind/blob/main/modal_shared/stacks.py"
click node_iam "https://github.com/overmind-core/overmind/blob/main/overbae/models/iam.py"
click node_mcp_server "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/server.py"
click node_mcp_catalog "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/catalog.py"
click node_mcp_resources "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/resources.py"
click node_mcp_eval_tools "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_evaluations.py"
click node_mcp_train_tools "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_finetuning.py"
click node_mcp_connector_tools "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_connectors.py"
click node_mcp_oauth "https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/oauth_routes.py"
click node_api "https://github.com/overmind-core/overmind/tree/main/overbae/api"
click node_modal "https://github.com/overmind-core/overmind/tree/main/overbae/modal"

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_console_ui toneBlue
class node_capabilities,node_traces,node_datasets toneAmber
class node_eval_models,node_eval_workflows,node_optimizer,node_inference_api toneMint
class node_finetuning_models,node_training,node_model_families,node_model_registry,node_deployment,node_deploy_reconcile,node_inference_client,node_inference_worker,node_context_budget,node_stack_config,node_modal,node_trained_weights toneRose
class node_iam,node_mcp_server,node_mcp_catalog,node_mcp_resources,node_mcp_eval_tools,node_mcp_train_tools,node_mcp_connector_tools,node_mcp_oauth,node_api,node_user,node_production_agent,node_mcp_client toneIndigo
```

## Components

### Console

- [Web console](https://github.com/overmind-core/overmind/tree/main/frontend/src): `frontend/src`

### Agent data

- [Capability graph](https://github.com/overmind-core/overmind/blob/main/overbae/models/capabilities.py): `overbae/models/capabilities.py`
- [Trace observability](https://github.com/overmind-core/overmind/blob/main/overbae/models/traces.py): `overbae/models/traces.py`
- [Datasets](https://github.com/overmind-core/overmind/blob/main/overbae/api/datasets.py): `overbae/api/datasets.py`

### Evaluation and improvement

- [Evaluation records](https://github.com/overmind-core/overmind/blob/main/overbae/models/evaluation.py): `overbae/models/evaluation.py`
- [Evaluation workflows](https://github.com/overmind-core/overmind/tree/main/overbae/services): `overbae/services`
- [Optimizer experiments](https://github.com/overmind-core/overmind/blob/main/overbae/models/optimizer.py): `overbae/models/optimizer.py`

### Model lifecycle

- [Fine-tuning jobs](https://github.com/overmind-core/overmind/blob/main/overbae/models/finetuning.py): `overbae/models/finetuning.py`
- [SFT training](https://github.com/overmind-core/overmind/blob/main/overbae/services/sft_assets/engine_unsloth.py): `overbae/services/sft_assets/engine_unsloth.py`
- [Model families](https://github.com/overmind-core/overmind/blob/main/modal_shared/modelfam/spec.py): `modal_shared/modelfam/spec.py`
- [Model registry](https://github.com/overmind-core/overmind/blob/main/overbae/core/model_registry.py): `overbae/core/model_registry.py`
- [Deployment orchestration](https://github.com/overmind-core/overmind/blob/main/overbae/services/deployment.py): `overbae/services/deployment.py`
- [Deployment reconciler](https://github.com/overmind-core/overmind/blob/main/overbae/tasks/inference_controller.py): `overbae/tasks/inference_controller.py`
- [Inference client](https://github.com/overmind-core/overmind/blob/main/overbae/services/inference_client.py): `overbae/services/inference_client.py`
- [vLLM serving](https://github.com/overmind-core/overmind/blob/main/overbae/modal/modal_vllm_worker.py): `overbae/modal/modal_vllm_worker.py`
- [Context budgeting](https://github.com/overmind-core/overmind/blob/main/modal_shared/context_budget.py): `modal_shared/context_budget.py`
- [Train/serve stacks](https://github.com/overmind-core/overmind/blob/main/modal_shared/stacks.py): `modal_shared/stacks.py`
- [Modal workers](https://github.com/overmind-core/overmind/tree/main/overbae/modal): `overbae/modal`
- **Model weights**

### API and integrations

- [Projects and identity](https://github.com/overmind-core/overmind/blob/main/overbae/models/iam.py): `overbae/models/iam.py`
- [MCP server](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/server.py): `overbae/services/mcp/server.py`
- [MCP tool catalog](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/catalog.py): `overbae/services/mcp/catalog.py`
- [MCP resources](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/resources.py): `overbae/services/mcp/resources.py`
- [Evaluation tools](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_evaluations.py): `overbae/services/mcp/tools_evaluations.py`
- [Fine-tuning tools](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_finetuning.py): `overbae/services/mcp/tools_finetuning.py`
- [Connector tools](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/tools_connectors.py): `overbae/services/mcp/tools_connectors.py`
- [MCP OAuth](https://github.com/overmind-core/overmind/blob/main/overbae/services/mcp/oauth_routes.py): `overbae/services/mcp/oauth_routes.py`
- [REST API](https://github.com/overmind-core/overmind/tree/main/overbae/api): `overbae/api`

### Other components

- **Agent builder**
- **Instrumented agent**
- **Coding agent**
- **OpenAI-compatible API**

## Connections

- Agent builder → Web console: uses (evidence: `README.md`)
- Web console → REST API: manages platform
- Instrumented agent → Trace observability: emits traces (evidence: `README.md`)
- Trace observability → Datasets: forms datasets (evidence: `README.md`)
- Agent builder → Capability graph: scans repository (evidence: `README.md`)
- Datasets → Evaluation workflows: evaluates (evidence: `README.md`)
- Capability graph → Evaluation workflows: defines metrics (evidence: `README.md`)
- Evaluation workflows → Evaluation records: records results
- Evaluation workflows → Optimizer experiments: scores experiments (evidence: `README.md`)
- Optimizer experiments → Agent builder: returns git diff (evidence: `README.md`)
- Datasets → Fine-tuning jobs: trains on data (evidence: `README.md`)
- Fine-tuning jobs → SFT training: runs fine-tuning
- SFT training → Model families: resolves family (evidence: `overbae/services/sft_assets/engine_unsloth.py`)
- SFT training → Model weights: produces weights
- Model families → Train/serve stacks: selects stack (evidence: `modal_shared/stacks.py`)
- Deployment reconciler → Deployment orchestration: reconciles deployments (evidence: `overbae/tasks/inference_controller.py`)
- Deployment orchestration → Modal workers: deploys models (evidence: `README.md`)
- Inference client → vLLM serving: sends routed requests (evidence: `overbae/services/inference_client.py`)
- vLLM serving → Context budgeting: reserves output tokens (evidence: `overbae/modal/modal_vllm_worker.py`)
- vLLM serving → Model families: resolves family (evidence: `overbae/modal/modal_vllm_worker.py`)
- vLLM serving → Model weights: loads weights
- vLLM serving → OpenAI-compatible API: serves inference (evidence: `README.md`)
- Agent builder → Coding agent: connects coding agent (evidence: `README.md`)
- Coding agent → MCP server: calls tools (evidence: `README.md`)
- MCP server → MCP tool catalog: dispatches tools (evidence: `overbae/services/mcp/server.py`)
- MCP server → MCP resources: lists resources (evidence: `overbae/services/mcp/server.py`)
- MCP tool catalog → Evaluation tools: registers tools (evidence: `overbae/services/mcp/catalog.py`)
- MCP tool catalog → Fine-tuning tools: registers tools (evidence: `overbae/services/mcp/catalog.py`)
- MCP tool catalog → Connector tools: registers tools (evidence: `overbae/services/mcp/catalog.py`)
- MCP server → MCP OAuth: authenticates clients (evidence: `overbae/services/mcp/server.py`)
- Coding agent → REST API: uses REST API (evidence: `README.md`)
