# obot-platform/obot architecture

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

- Interactive diagram: https://gitdiagram.com/obot-platform/obot
- Repository: https://github.com/obot-platform/obot

## Overview

Obot is an organizational platform for governing AI clients, model access, MCP tools, hosted workloads, and related activity. A typical user or client discovers approved MCP servers or skills through the CLI or UI, then connects through Obot’s gateways, where access and policy controls apply; activity can be audited across gateway and device sources. The README documents additional device-management, catalog, hosted-agent, identity, and export capabilities. Edges reflect those documented responsibilities; sampled source was limited and does not establish every subsystem’s wiring.

Main entry points: [`pkg/api/server/server.go`](https://github.com/obot-platform/obot/blob/main/pkg/api/server/server.go) (API server), [`pkg/auditlog/source.go`](https://github.com/obot-platform/obot/blob/main/pkg/auditlog/source.go) (Activity audit), [`pkg/cli/root.go`](https://github.com/obot-platform/obot/blob/main/pkg/cli/root.go) (Obot CLI), [`pkg/api/handlers/mcpgateway/handler.go`](https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/mcpgateway/handler.go) (MCP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Obot CLI<br/>[root.go]"]
  node_web_ui["Web UI<br/>[handler.go]"]
end

subgraph group_gateway["Governed gateways"]
  node_mcp_gateway["MCP gateway<br/>[handler.go]"]
  node_llm_gateway["LLM gateway<br/>[llmproxy.go]"]
  node_mcp_runtime["MCP runtime<br/>[manager.go]"]
end

subgraph group_catalog_workloads["Catalogs and workloads"]
  node_registries["MCP and skills registries<br/>[handler.go]"]
  node_skill_cli["Skills management<br/>[skills.go]"]
  node_hosted_agents["Hosted agents<br/>[backend.go]"]
end

subgraph group_governance["Identity and audit"]
  node_model_policy["Model access policy<br/>[helper.go]"]
  node_device_governance["Device governance<br/>[devicescans.go]"]
  node_identity_access["Identity and access<br/>[authz.go]"]
  node_audit["Activity audit<br/>[source.go]"]
  node_audit_export["Audit export<br/>[storage.go]"]
end

subgraph group_runtime["Platform runtime"]
  node_api_server["API server<br/>[server.go]"]
  node_controllers["Resource controllers<br/>[controller.go]"]
  node_platform_storage[("Platform storage<br/>[server.go]")]
end

node_user(("Users and admins"))
node_ai_clients(("AI clients"))
node_mcp_servers{{"MCP servers"}}
node_model_providers{{"Model providers"}}
node_git_providers{{"Git providers"}}

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_web_ui
node_ai_clients -->|"connects to"| node_mcp_gateway
node_ai_clients -->|"connects to"| node_llm_gateway
node_cli -->|"requests services"| node_api_server
node_web_ui -->|"requests services"| node_api_server
node_api_server -->|"authorizes requests"| node_identity_access
node_api_server -->|"records API activity"| node_audit
node_mcp_gateway -->|"manages sessions"| node_mcp_runtime
node_mcp_gateway -->|"proxies MCP traffic"| node_mcp_servers
node_mcp_gateway -->|"enforces access"| node_identity_access
node_llm_gateway -->|"proxies model requests"| node_model_providers
node_llm_gateway -->|"restricts models"| node_model_policy
node_registries -.->|"indexes catalogs"| node_git_providers
node_cli -->|"discovers approved items"| node_registries
node_cli -->|"manages skills"| node_skill_cli
node_controllers -->|"reconciles workloads"| node_hosted_agents
node_mcp_runtime -->|"records MCP activity"| node_audit
node_llm_gateway -->|"records model activity"| node_audit
node_device_governance -->|"contributes device activity"| node_audit
node_audit -->|"exports activity"| node_audit_export
node_controllers -->|"reconciles resources"| node_platform_storage
node_api_server -->|"reads and writes"| node_platform_storage

click node_cli "https://github.com/obot-platform/obot/blob/main/pkg/cli/root.go"
click node_web_ui "https://github.com/obot-platform/obot/blob/main/ui/handler.go"
click node_api_server "https://github.com/obot-platform/obot/blob/main/pkg/api/server/server.go"
click node_mcp_gateway "https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/mcpgateway/handler.go"
click node_llm_gateway "https://github.com/obot-platform/obot/blob/main/pkg/gateway/server/llmproxy.go"
click node_mcp_runtime "https://github.com/obot-platform/obot/blob/main/pkg/mcp/manager.go"
click node_model_policy "https://github.com/obot-platform/obot/blob/main/pkg/modelaccesspolicy/helper.go"
click node_registries "https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/registry/handler.go"
click node_skill_cli "https://github.com/obot-platform/obot/blob/main/pkg/cli/skills.go"
click node_hosted_agents "https://github.com/obot-platform/obot/blob/main/pkg/agentbackend/backend.go"
click node_device_governance "https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/devicescans.go"
click node_identity_access "https://github.com/obot-platform/obot/blob/main/pkg/api/authz/authz.go"
click node_audit "https://github.com/obot-platform/obot/blob/main/pkg/auditlog/source.go"
click node_audit_export "https://github.com/obot-platform/obot/blob/main/pkg/auditlogexport/storage.go"
click node_controllers "https://github.com/obot-platform/obot/blob/main/pkg/controller/controller.go"
click node_platform_storage "https://github.com/obot-platform/obot/blob/main/pkg/storage/server.go"

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_cli,node_web_ui,node_user,node_ai_clients toneBlue
class node_mcp_gateway,node_llm_gateway,node_mcp_runtime toneAmber
class node_registries,node_skill_cli,node_hosted_agents,node_mcp_servers toneMint
class node_model_policy,node_device_governance,node_identity_access,node_audit,node_audit_export toneRose
class node_api_server,node_controllers,node_platform_storage,node_model_providers,node_git_providers toneIndigo
```

## Components

### User interfaces

- [Obot CLI](https://github.com/obot-platform/obot/blob/main/pkg/cli/root.go): `pkg/cli/root.go`
- [Web UI](https://github.com/obot-platform/obot/blob/main/ui/handler.go): `ui/handler.go`

### Governed gateways

- [MCP gateway](https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/mcpgateway/handler.go): `pkg/api/handlers/mcpgateway/handler.go`
- [LLM gateway](https://github.com/obot-platform/obot/blob/main/pkg/gateway/server/llmproxy.go): `pkg/gateway/server/llmproxy.go`
- [MCP runtime](https://github.com/obot-platform/obot/blob/main/pkg/mcp/manager.go): `pkg/mcp/manager.go`

### Catalogs and workloads

- [MCP and skills registries](https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/registry/handler.go): `pkg/api/handlers/registry/handler.go`
- [Skills management](https://github.com/obot-platform/obot/blob/main/pkg/cli/skills.go): `pkg/cli/skills.go`
- [Hosted agents](https://github.com/obot-platform/obot/blob/main/pkg/agentbackend/backend.go): `pkg/agentbackend/backend.go`

### Identity and audit

- [Model access policy](https://github.com/obot-platform/obot/blob/main/pkg/modelaccesspolicy/helper.go): `pkg/modelaccesspolicy/helper.go`
- [Device governance](https://github.com/obot-platform/obot/blob/main/pkg/api/handlers/devicescans.go): `pkg/api/handlers/devicescans.go`
- [Identity and access](https://github.com/obot-platform/obot/blob/main/pkg/api/authz/authz.go): `pkg/api/authz/authz.go`
- [Activity audit](https://github.com/obot-platform/obot/blob/main/pkg/auditlog/source.go): `pkg/auditlog/source.go`
- [Audit export](https://github.com/obot-platform/obot/blob/main/pkg/auditlogexport/storage.go): `pkg/auditlogexport/storage.go`

### Platform runtime

- [API server](https://github.com/obot-platform/obot/blob/main/pkg/api/server/server.go): `pkg/api/server/server.go`
- [Resource controllers](https://github.com/obot-platform/obot/blob/main/pkg/controller/controller.go): `pkg/controller/controller.go`
- [Platform storage](https://github.com/obot-platform/obot/blob/main/pkg/storage/server.go): `pkg/storage/server.go`

### Other components

- **Users and admins**
- **AI clients**
- **MCP servers**
- **Model providers**
- **Git providers**

## Connections

- Users and admins → Obot CLI: uses
- Users and admins → Web UI: uses
- AI clients → MCP gateway: connects to
- AI clients → LLM gateway: connects to
- Obot CLI → API server: requests services
- Web UI → API server: requests services
- API server → Identity and access: authorizes requests
- API server → Activity audit: records API activity
- MCP gateway → MCP runtime: manages sessions
- MCP gateway → MCP servers: proxies MCP traffic
- MCP gateway → Identity and access: enforces access
- LLM gateway → Model providers: proxies model requests
- LLM gateway → Model access policy: restricts models
- MCP and skills registries → Git providers: indexes catalogs
- Obot CLI → MCP and skills registries: discovers approved items
- Obot CLI → Skills management: manages skills
- Resource controllers → Hosted agents: reconciles workloads
- MCP runtime → Activity audit: records MCP activity
- LLM gateway → Activity audit: records model activity
- Device governance → Activity audit: contributes device activity
- Activity audit → Audit export: exports activity
- Resource controllers → Platform storage: reconciles resources
- API server → Platform storage: reads and writes
