# vstorm-co/agenticos architecture

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

- Interactive diagram: https://gitdiagram.com/vstorm-co/agenticos
- Repository: https://github.com/vstorm-co/agenticos

## Overview

AgenticOS is a self-hosted AI teammate platform: users build and govern agents, then work with them in shared chat. The central runtime route reaches agent execution, where configurable capabilities provide tools such as knowledge search, browsing, skills, MCP, code execution, and approvals. RAG ingestion and vector search form a distinct knowledge lifecycle; background jobs support durable work. The README documents these product branches, while the sampled source is incomplete, so unverified connections are shown as dashed with no evidence path.

Main entry points: [`backend/app/agents/factory.py`](https://github.com/vstorm-co/agenticos/blob/main/backend/app/agents/factory.py) (Agent runtime), [`backend/app/services/rag/ingestion.py`](https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/ingestion.py) (Document ingestion), [`backend/app/main.py`](https://github.com/vstorm-co/agenticos/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/routes/v1`](https://github.com/vstorm-co/agenticos/tree/main/backend/app/api/routes/v1) (Product API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry"]
  node_frontend["Web console"]
  node_api["FastAPI application<br/>[main.py]"]
  node_routes["Product API"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_runtime["Agent runtime<br/>[factory.py]"]
  node_toolbox["Agent capabilities"]
  node_model["Model providers"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_rag_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_rag_tasks["Sync workers<br/>[rag_tasks.py]"]
  node_vectorstore[("Vector search<br/>[vectorstore.py]")]
  node_rag_models["RAG settings<br/>[models.py]"]
  node_files["File storage<br/>[file_storage.py]"]
end

subgraph group_governance["Governance and state"]
  node_database[("Application database")]
  node_background["Background jobs<br/>[background.py]"]
  node_permissions["Access controls<br/>[permissions.py]"]
  node_audit["Audit trail<br/>[audit.py]"]
end

subgraph group_integrations["Channels and integrations"]
  node_channels["Team channels"]
  node_mcp["MCP integrations<br/>[mcp.py]"]
  node_coding["Coding agents"]
end

node_user(("Team user"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"sends requests"| node_api
node_api -->|"mounts routes"| node_routes
node_routes -.->|"starts agent runs"| node_agent_runtime
node_agent_runtime -.->|"uses capabilities"| node_toolbox
node_agent_runtime -->|"calls models"| node_model
node_user -.->|"chats with"| node_agent_runtime
node_toolbox -.->|"searches knowledge"| node_rag_ingestion
node_rag_tasks -->|"processes documents"| node_rag_ingestion
node_rag_ingestion -->|"indexes documents"| node_vectorstore
node_vectorstore -->|"uses settings"| node_rag_models
node_rag_ingestion -.->|"ingests files"| node_files
node_rag_tasks -->|"reads document state"| node_database
node_routes -.->|"checks access"| node_permissions
node_agent_runtime -.->|"records activity"| node_audit
node_api -->|"starts background work"| node_background
node_user -->|"works through"| node_channels
node_channels -.->|"routes messages"| node_agent_runtime
node_agent_runtime -->|"uses MCP"| node_mcp
node_agent_runtime -->|"delegates coding"| node_coding
node_agent_runtime -.->|"persists runs"| node_database

click node_frontend "https://github.com/vstorm-co/agenticos/tree/main/frontend/src"
click node_api "https://github.com/vstorm-co/agenticos/blob/main/backend/app/main.py"
click node_routes "https://github.com/vstorm-co/agenticos/tree/main/backend/app/api/routes/v1"
click node_agent_runtime "https://github.com/vstorm-co/agenticos/blob/main/backend/app/agents/factory.py"
click node_toolbox "https://github.com/vstorm-co/agenticos/tree/main/backend/app/agents/capabilities"
click node_rag_ingestion "https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/ingestion.py"
click node_rag_tasks "https://github.com/vstorm-co/agenticos/blob/main/backend/app/worker/tasks/rag_tasks.py"
click node_vectorstore "https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/vectorstore.py"
click node_rag_models "https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/models.py"
click node_files "https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/file_storage.py"
click node_database "https://github.com/vstorm-co/agenticos/tree/main/backend/app/db"
click node_background "https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/background.py"
click node_permissions "https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/permissions.py"
click node_audit "https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/audit.py"
click node_channels "https://github.com/vstorm-co/agenticos/tree/main/backend/app/services/channels"
click node_mcp "https://github.com/vstorm-co/agenticos/blob/main/backend/app/agents/mcp.py"
click node_coding "https://github.com/vstorm-co/agenticos/tree/main/backend/app/agents/capabilities/coding_agent"

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_api,node_routes,node_user toneBlue
class node_agent_runtime,node_toolbox,node_model toneAmber
class node_rag_ingestion,node_rag_tasks,node_vectorstore,node_rag_models,node_files toneMint
class node_database,node_background,node_permissions,node_audit toneRose
class node_channels,node_mcp,node_coding toneIndigo
```

## Components

### Product entry

- [Web console](https://github.com/vstorm-co/agenticos/tree/main/frontend/src): `frontend/src`
- [FastAPI application](https://github.com/vstorm-co/agenticos/blob/main/backend/app/main.py): `backend/app/main.py`
- [Product API](https://github.com/vstorm-co/agenticos/tree/main/backend/app/api/routes/v1): `backend/app/api/routes/v1`

### Agent runtime

- [Agent runtime](https://github.com/vstorm-co/agenticos/blob/main/backend/app/agents/factory.py): `backend/app/agents/factory.py`
- [Agent capabilities](https://github.com/vstorm-co/agenticos/tree/main/backend/app/agents/capabilities): `backend/app/agents/capabilities`
- **Model providers**

### Knowledge lifecycle

- [Document ingestion](https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/ingestion.py): `backend/app/services/rag/ingestion.py`
- [Sync workers](https://github.com/vstorm-co/agenticos/blob/main/backend/app/worker/tasks/rag_tasks.py): `backend/app/worker/tasks/rag_tasks.py`
- [Vector search](https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/vectorstore.py): `backend/app/services/rag/vectorstore.py`
- [RAG settings](https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/rag/models.py): `backend/app/services/rag/models.py`
- [File storage](https://github.com/vstorm-co/agenticos/blob/main/backend/app/services/file_storage.py): `backend/app/services/file_storage.py`

### Governance and state

- [Application database](https://github.com/vstorm-co/agenticos/tree/main/backend/app/db): `backend/app/db`
- [Background jobs](https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/background.py): `backend/app/core/background.py`
- [Access controls](https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/permissions.py): `backend/app/core/permissions.py`
- [Audit trail](https://github.com/vstorm-co/agenticos/blob/main/backend/app/core/audit.py): `backend/app/core/audit.py`

### Channels and integrations

- [Team channels](https://github.com/vstorm-co/agenticos/tree/main/backend/app/services/channels): `backend/app/services/channels`
- [MCP integrations](https://github.com/vstorm-co/agenticos/blob/main/backend/app/agents/mcp.py): `backend/app/agents/mcp.py`
- [Coding agents](https://github.com/vstorm-co/agenticos/tree/main/backend/app/agents/capabilities/coding_agent): `backend/app/agents/capabilities/coding_agent`

### Other components

- **Team user**

## Connections

- Team user → Web console: uses (evidence: `README.md`)
- Web console → FastAPI application: sends requests
- FastAPI application → Product API: mounts routes (evidence: `backend/app/main.py`)
- Product API → Agent runtime: starts agent runs
- Agent runtime → Agent capabilities: uses capabilities (evidence: `README.md`)
- Agent runtime → Model providers: calls models (evidence: `README.md`)
- Team user → Agent runtime: chats with (evidence: `README.md`)
- Agent capabilities → Document ingestion: searches knowledge (evidence: `README.md`)
- Sync workers → Document ingestion: processes documents (evidence: `backend/app/worker/tasks/rag_tasks.py`)
- Document ingestion → Vector search: indexes documents (evidence: `backend/app/services/rag/ingestion.py`)
- Vector search → RAG settings: uses settings (evidence: `backend/app/services/rag/vectorstore.py`)
- Document ingestion → File storage: ingests files
- Sync workers → Application database: reads document state (evidence: `backend/app/worker/tasks/rag_tasks.py`)
- Product API → Access controls: checks access (evidence: `backend/app/api/routes/v1/_sharing_routes.py`)
- Agent runtime → Audit trail: records activity
- FastAPI application → Background jobs: starts background work (evidence: `backend/app/main.py`)
- Team user → Team channels: works through (evidence: `README.md`)
- Team channels → Agent runtime: routes messages (evidence: `README.md`)
- Agent runtime → MCP integrations: uses MCP (evidence: `README.md`)
- Agent runtime → Coding agents: delegates coding (evidence: `README.md`)
- Agent runtime → Application database: persists runs
