# archestra-ai/archestra architecture

> Architecture diagram of the GitHub repository archestra-ai/archestra, 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/archestra-ai/archestra
- Repository: https://github.com/archestra-ai/archestra

## Overview

Archestra is an enterprise AI platform serving end users, agents, and developer clients through chat, LLM, and MCP entry points. A typical interaction is initiated in a frontend or client, handled by a backend route or proxy, sent to a model or tool, and governed by identity, permissions, and guardrails. The README also describes agent triggers and delegation, knowledge retrieval, mini apps, MCP/A2A gateways, and observability. Those documented capabilities are represented, but their detailed wiring is not established by the sampled source excerpts.

Main entry points: [`platform/backend/src/agents/agent-run-stream.ts`](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/agents/agent-run-stream.ts) (Agent Runtime), [`platform/backend/src/routes/proxy/llm-proxy-handler.ts`](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/proxy/llm-proxy-handler.ts) (LLM Proxy), [`platform/backend/src/database/index.ts`](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/index.ts) (Platform Database), [`platform/frontend/src/app/_parts/query-client-provider.tsx`](https://github.com/archestra-ai/archestra/blob/main/platform/frontend/src/app/_parts/query-client-provider.tsx) (Web Frontend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_frontend["Web Frontend"]
  node_chat["Chat &amp; Apps<br/>[app.routes.ts]"]
  node_llm_oauth_ui["LLM OAuth UI"]
end

subgraph group_gateway["Gateway Runtime"]
  node_oauth_routes["OAuth Client Routes"]
  node_llm_proxy["LLM Proxy"]
  node_proxy_config["Proxy Configuration"]
  node_llm_client["Provider Client<br/>[llm-client.ts]"]
end

subgraph group_agents_tools["Agents &amp; Tools"]
  node_agents["Agent Runtime"]
  node_mcp_gateway["MCP Gateway<br/>[index.ts]"]
  node_a2a_gateway["A2A Gateway<br/>[a2a-manager.ts]"]
  node_knowledge["Knowledge Base<br/>[knowledge-base.ts]"]
  node_apps["Mini Apps<br/>[app.routes.ts]"]
  node_sandbox["Sandbox Execution<br/>[lib.rs]"]
  node_orchestration["MCP Orchestration<br/>[mcp-gateways.ts]"]
  node_registry["Private MCP Registry<br/>[mcp-servers.ts]"]
end

subgraph group_governance["Security &amp; Policy"]
  node_guardrails["Guardrails"]
  node_identity_access["Identity &amp; Access<br/>[index.ts]"]
  node_environments["Environments &amp; Limits<br/>[environment.ts]"]
end

subgraph group_platform_state["Platform State"]
  node_oauth_model["OAuth Client Model"]
  node_observability["Observability<br/>[interaction.ts]"]
  node_database[("Platform Database<br/>[index.ts]")]
end

node_users(("Users"))
node_developer_clients(("Developer Clients"))
node_llm_providers{{"LLM Providers"}}
node_mcp_services{{"MCP Services"}}

node_users -->|"use"| node_frontend
node_developer_clients -->|"request"| node_llm_proxy
node_frontend -->|"invoke"| node_chat
node_frontend -->|"manage clients"| node_llm_oauth_ui
node_llm_oauth_ui -->|"configure"| node_oauth_routes
node_oauth_routes -->|"manage records"| node_oauth_model
node_chat -->|"start runs"| node_agents
node_llm_proxy -->|"dispatch"| node_llm_client
node_llm_client -->|"call model"| node_llm_providers
node_llm_proxy -->|"apply policy"| node_guardrails
node_llm_proxy -->|"record interactions"| node_observability
node_proxy_config -->|"read/write config"| node_database
node_oauth_model -->|"read/write clients"| node_database
node_oauth_routes -->|"authorize"| node_identity_access
node_agents -->|"request inference"| node_llm_proxy
node_agents -->|"invoke tools"| node_mcp_gateway
node_mcp_gateway -->|"dispatch tools"| node_mcp_services
node_agents -.->|"retrieve context"| node_knowledge
node_agents -.->|"execute code"| node_sandbox
node_orchestration -->|"manage servers"| node_registry
node_a2a_gateway -->|"trigger agents"| node_agents
node_agents -->|"emit telemetry"| node_observability
node_guardrails -->|"read policy state"| node_database
node_identity_access -->|"read identity state"| node_database
node_environments -->|"persist limits"| node_database

click node_frontend "https://github.com/archestra-ai/archestra/blob/main/platform/frontend/src/app/_parts/query-client-provider.tsx"
click node_chat "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/app/app.routes.ts"
click node_llm_oauth_ui "https://github.com/archestra-ai/archestra/blob/main/platform/frontend/src/components/llm-oauth-client-dialogs.tsx"
click node_oauth_routes "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/llm-oauth-clients.ts"
click node_oauth_model "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/models/llm-oauth-client.ts"
click node_llm_proxy "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/proxy/llm-proxy-handler.ts"
click node_proxy_config "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/llm-proxy/llm-proxy.routes.ts"
click node_llm_client "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/clients/llm-client.ts"
click node_agents "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/agents/agent-run-stream.ts"
click node_mcp_gateway "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/index.ts"
click node_a2a_gateway "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/agents/a2a/a2a-manager.ts"
click node_knowledge "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/knowledge-base.ts"
click node_apps "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/app/app.routes.ts"
click node_guardrails "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/openappa-coverage/openappa-coverage.routes.ts"
click node_identity_access "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/auth/index.ts"
click node_sandbox "https://github.com/archestra-ai/archestra/blob/main/platform/archestra-rs/sandbox-core/src/lib.rs"
click node_orchestration "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/mcp-gateways.ts"
click node_registry "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/mcp-servers.ts"
click node_environments "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/environment.ts"
click node_observability "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/interaction.ts"
click node_database "https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/index.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_frontend,node_chat,node_llm_oauth_ui,node_users,node_developer_clients toneBlue
class node_oauth_routes,node_llm_proxy,node_proxy_config,node_llm_client toneAmber
class node_agents,node_mcp_gateway,node_a2a_gateway,node_knowledge,node_apps,node_sandbox,node_orchestration,node_registry toneMint
class node_guardrails,node_identity_access,node_environments toneRose
class node_oauth_model,node_observability,node_database,node_llm_providers,node_mcp_services toneIndigo
```

## Components

### User Interfaces

- [Web Frontend](https://github.com/archestra-ai/archestra/blob/main/platform/frontend/src/app/_parts/query-client-provider.tsx): `platform/frontend/src/app/_parts/query-client-provider.tsx`
- [Chat & Apps](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/app/app.routes.ts): `platform/backend/src/routes/app/app.routes.ts`
- [LLM OAuth UI](https://github.com/archestra-ai/archestra/blob/main/platform/frontend/src/components/llm-oauth-client-dialogs.tsx): `platform/frontend/src/components/llm-oauth-client-dialogs.tsx`

### Gateway Runtime

- [OAuth Client Routes](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/llm-oauth-clients.ts): `platform/backend/src/routes/llm-oauth-clients.ts`
- [LLM Proxy](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/proxy/llm-proxy-handler.ts): `platform/backend/src/routes/proxy/llm-proxy-handler.ts`
- [Proxy Configuration](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/llm-proxy/llm-proxy.routes.ts): `platform/backend/src/routes/llm-proxy/llm-proxy.routes.ts`
- [Provider Client](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/clients/llm-client.ts): `platform/backend/src/clients/llm-client.ts`

### Agents & Tools

- [Agent Runtime](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/agents/agent-run-stream.ts): `platform/backend/src/agents/agent-run-stream.ts`
- [MCP Gateway](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/index.ts): `platform/backend/src/archestra-mcp-server/index.ts`
- [A2A Gateway](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/agents/a2a/a2a-manager.ts): `platform/backend/src/agents/a2a/a2a-manager.ts`
- [Knowledge Base](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/knowledge-base.ts): `platform/backend/src/database/schemas/knowledge-base.ts`
- [Mini Apps](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/app/app.routes.ts): `platform/backend/src/routes/app/app.routes.ts`
- [Sandbox Execution](https://github.com/archestra-ai/archestra/blob/main/platform/archestra-rs/sandbox-core/src/lib.rs): `platform/archestra-rs/sandbox-core/src/lib.rs`
- [MCP Orchestration](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/mcp-gateways.ts): `platform/backend/src/archestra-mcp-server/mcp-gateways.ts`
- [Private MCP Registry](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/archestra-mcp-server/mcp-servers.ts): `platform/backend/src/archestra-mcp-server/mcp-servers.ts`

### Security & Policy

- [Guardrails](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/routes/openappa-coverage/openappa-coverage.routes.ts): `platform/backend/src/routes/openappa-coverage/openappa-coverage.routes.ts`
- [Identity & Access](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/auth/index.ts): `platform/backend/src/auth/index.ts`
- [Environments & Limits](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/environment.ts): `platform/backend/src/database/schemas/environment.ts`

### Platform State

- [OAuth Client Model](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/models/llm-oauth-client.ts): `platform/backend/src/models/llm-oauth-client.ts`
- [Observability](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/schemas/interaction.ts): `platform/backend/src/database/schemas/interaction.ts`
- [Platform Database](https://github.com/archestra-ai/archestra/blob/main/platform/backend/src/database/index.ts): `platform/backend/src/database/index.ts`

### Other components

- **Users**
- **Developer Clients**
- **LLM Providers**
- **MCP Services**

## Connections

- Users → Web Frontend: use
- Developer Clients → LLM Proxy: request
- Web Frontend → Chat & Apps: invoke
- Web Frontend → LLM OAuth UI: manage clients
- LLM OAuth UI → OAuth Client Routes: configure
- OAuth Client Routes → OAuth Client Model: manage records
- Chat & Apps → Agent Runtime: start runs
- LLM Proxy → Provider Client: dispatch
- Provider Client → LLM Providers: call model
- LLM Proxy → Guardrails: apply policy
- LLM Proxy → Observability: record interactions
- Proxy Configuration → Platform Database: read/write config
- OAuth Client Model → Platform Database: read/write clients
- OAuth Client Routes → Identity & Access: authorize
- Agent Runtime → LLM Proxy: request inference
- Agent Runtime → MCP Gateway: invoke tools
- MCP Gateway → MCP Services: dispatch tools
- Agent Runtime → Knowledge Base: retrieve context
- Agent Runtime → Sandbox Execution: execute code
- MCP Orchestration → Private MCP Registry: manage servers
- A2A Gateway → Agent Runtime: trigger agents
- Agent Runtime → Observability: emit telemetry
- Guardrails → Platform Database: read policy state
- Identity & Access → Platform Database: read identity state
- Environments & Limits → Platform Database: persist limits