# agentark-ai/agentark architecture

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

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

## Overview

1. **Repository shape**
   - This is a multi-runtime monorepo centered on a **Rust backend** (`src/`) with a **TypeScript React frontend** (`frontend/`), plus **mobile/desktop companion clients** (`clients/companion/`), **channel bridges** (`bridges/`), and Docker-based deployment/runtime files.
   - The codebase is organized as a local AI operating system rather than a single app: chat, tasks, memory, integrations, automation, self-improvement, and observability are all first-class subsystems.

2. **Primary control plane**
   - The Rust server is the main control plane. It exposes many HTTP API groups under `src/channels/http/` for core chat, runtime, admin, analytics, app control, integrations, automation, tunnels, and action APIs.
   - The web UI in `frontend/` talks to this backend through a client layer (`frontend/src/api/client.ts`) and renders the main Mission Control surfaces such as chat, settings, memory, reflect, sentinel, evolve, and pulse.

3. **Core domain layers**
   - `src/core/` contains the product’s main logic, split into domains like **agent**, **automation**, **connectivity**, **knowledge**, **model**, **orchestration**, **runtime**, **self_evolve**, **swarm**, and **platform**.
   - These layers are where decisions are made: prompt construction, memory retrieval, task routing, model selection/failover, background learning, policy enforcement, and orchestration of tool execution.

4. **Agent loop and reasoning flow**
   - The agent path starts with conversation/state handling in `src/core/agent/conversation/`, then moves through prompt/spine construction in `src/core/agent/spine/`, runtime execution in `src/core/agent/runtime/`, and memory/ops helpers in `src/core/agent/operations/`.
   - The model layer (`src/core/model/`) abstracts provider access, context budgeting, failover, and prompt policy so the system can work with Ollama or remote LLM APIs without changing the higher-level orchestration.

5. **Execution and tool isolation**
   - Tool execution is separated into `src/runtime/action_runtime/` and `src/runtime/`, with support for native execution, CLI execution, code execution, browser/web access, Docker-backed WASM execution, and governance/authorization checks.
   - This boundary is important: the agent does not directly “do everything” inside the model loop. Actions are validated, authorized, executed, and then recorded with proofs/traces for later review.

6. **Security and trust boundaries**
   - Security is explicit and layered: `src/security/` handles abuse tracking, trust boundaries, action guards, outbound filtering, tool-argument validation, privacy normalization/PII handling, and review policies.
   - Secrets are managed through encrypted storage (`src/crypto/`, `src/storage/encrypted.rs`, `src/core/runtime/config/secrets.rs`), and approvals/guards sit between model intent and real-world effects.

7. **Persistence and local data model**
   - The app is backed by a substantial local persistence layer in `src/storage/`, which includes entities and repositories for conversations, messages, documents, memory, tasks, runs, traces, approval logs, notifications, webhooks, browser sessions, and usage.
   - This suggests a “local workspace database” architecture: operational state, audit history, memory, and configuration all live in the local stack, primarily behind Postgres plus file-backed artifacts in the data volume.

8. **Automation, background work, and supervision**
   - Long-running behavior is handled by `src/core/automation/` and `src/core/connectivity/channels/` with watchers, runs, background sessions, task routing, and reminder/follow-up flows.
   - The Sentinel/Pulse style supervision surfaces are backed by runtime health checks, readiness, update operations, and monitoring models in `src/core/runtime/operations/` and `src/sentinel/`, making background work observable and restartable.

9. **Integrations and external connectivity**
   - Integrations are split into domain-specific modules under `src/integrations/` for browsers, messaging, productivity, devices, commerce, Google, media, and more, while `src/channels/messaging/` covers outbound messaging platforms like Slack, Telegram, WhatsApp, Teams, Matrix, Signal, and others.
   - Webhooks, custom APIs, MCP, and external gateways are handled as separate integration surfaces, which keeps third-party connectivity out of the core agent loop and makes each connector an explicit boundary.

10. **Companion devices and paired clients**
   - The `clients/companion/` subtree contains native companions for **Android**, **iOS**, **desktop**, and a **minimal Python custom-device client**, all of which speak a shared companion protocol schema in `clients/companion/protocol/`.
   - These clients appear to be for authenticated device pairing and scoped remote command/control, with token storage and websocket clients showing that the backend remains the authority while devices act as constrained endpoints.

11. **Bridges and specialized sidecars**
   - The `bridges/` directory contains standalone services for capabilities that are awkward to embed directly in Rust: Playwright/browser automation, WhatsApp bridging, voice bridging, and a Python-based GEPA optimizer bridge.
   - These are operationally separate containers/processes, which keeps heavyweight browser/audio/optimizer dependencies out of the main Rust binary while still exposing them to the control plane.

12. **Self-evolution and learning loop**
   - `src/core/self_evolve/` is the learning subsystem: it tracks opportunities, benchmarks, gates, routing/prompt evolution, optimizer integration, and runtime self-tuning.
   - This is tightly coupled to memory, traces, usage, and evaluation data from storage/repositories, so the system can propose and validate changes to prompts, routing, and context-saving behavior rather than learning only inside the model session.

13. **Frontend architecture**
   - The frontend is a large React/Vite application with many feature panels and pages: chat, tasks, memory, settings, analytics, integrations, voice, apps, traces, and the Ark Core surfaces.
   - It is presentation-heavy and stateful at the UI layer, but it relies on the Rust backend for durable state, action execution, and authority. The UI is effectively the operator console for the entire local AI stack.

14. **Deployment/runtime topology**
   - The repository is designed for **Docker Compose** as the default deployment shape, with Postgres, the Rust services, the frontend, and supporting containers started together.
   - The README and compose files indicate optional low-memory mode, managed backups, remote access/tunnels, and bundled runtime dependencies such as browser tooling, Docker CLI, and embeddings services. This makes the architecture a self-hosted local cluster rather than a single process.

15. **What to draw in an architecture diagram**
   - Model the system as: **UI/client surfaces** on top, **Rust control plane APIs** in the middle, then **core domain services** for agent logic, memory, automation, self-evolve, and integrations, with **execution/runtime sandboxes** and **storage/security** as cross-cutting layers.
   - Add separate external-boundary boxes for **LLM providers**, **messaging platforms**, **browser/web services**, **Google/productivity services**, **companion devices**, and **Docker/WASM execution**, because those are the main places data leaves or returns to the system.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/agentark-ai/agentark/blob/main/frontend/src/api/client.ts) (API client), [`src/storage`](https://github.com/agentark-ai/agentark/tree/main/src/storage) (Storage), [`src/core/agent`](https://github.com/agentark-ai/agentark/tree/main/src/core/agent) (Agent loop), [`src/runtime/action_runtime`](https://github.com/agentark-ai/agentark/tree/main/src/runtime/action_runtime) (Action runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Mission Control<br/>React UI<br/>[App.tsx]"]
  node_frontend_api["API client<br/>TS client<br/>[client.ts]"]
  node_frontend_panels["UI panels<br/>Feature pages"]
end

subgraph group_backend["Rust control plane"]
  node_http_core["Core APIs<br/>HTTP control"]
  node_http_runtime["Runtime APIs<br/>HTTP control"]
  node_http_app["App APIs<br/>HTTP control"]
  node_http_automation["Automation APIs<br/>HTTP control"]
  node_http_integrations["Integration APIs<br/>HTTP control"]
  node_http_admin["Admin APIs<br/>HTTP control"]
end

subgraph group_core["Core domains"]
  node_agent_loop{{"Agent loop<br/>Reasoning engine"}}
  node_model_layer["Model layer<br/>LLM abstraction"]
  node_orchestration["Orchestration<br/>Planner/executor"]
  node_automation_core["Automation<br/>Background work"]
  node_knowledge_core["Knowledge<br/>Memory/search"]
  node_self_evolve{{"Self-evolve<br/>Learning loop"}}
  node_swarm_core["Swarm<br/>Multi-agent"]
end

subgraph group_runtime["Execution and trust"]
  node_action_runtime[("Action runtime<br/>Sandbox executor")]
  node_security{{"Security<br/>Trust boundary"}}
  node_storage[("Storage<br/>Local persistence")]
  node_connectivity["Connectivity<br/>Channels and gateways"]
end

subgraph group_edges["External boundaries"]
  node_companion_clients["Companions<br/>Mobile/desktop clients"]
  node_messaging_platforms["Messaging platforms<br/>External channels"]
  node_llm_providers(("LLM providers<br/>External model APIs"))
  node_browser_web["Browser/web<br/>External automation"]
  node_google_services["Google services<br/>External SaaS"]
  node_bridge_services["Sidecar bridges<br/>Auxiliary services"]
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_panels -->|"loads data"| node_frontend_api
node_frontend_api -->|"chat/control"| node_http_core
node_frontend_api -->|"runtime state"| node_http_runtime
node_frontend_api -->|"app surfaces"| node_http_app
node_frontend_api -->|"supervision"| node_http_automation
node_frontend_api -->|"connectors"| node_http_integrations
node_frontend_api -->|"admin"| node_http_admin
node_http_core -->|"drives"| node_agent_loop
node_http_runtime -->|"memory"| node_knowledge_core
node_http_runtime -->|"model control"| node_model_layer
node_http_app -->|"pairing/control"| node_companion_clients
node_http_automation -->|"supervises"| node_automation_core
node_http_automation -->|"evolution"| node_self_evolve
node_http_integrations -->|"routes"| node_connectivity
node_http_admin -->|"enforces"| node_security
node_agent_loop -->|"queries"| node_model_layer
node_agent_loop -->|"plans"| node_orchestration
node_agent_loop -->|"retrieves"| node_knowledge_core
node_orchestration -->|"executes"| node_action_runtime
node_action_runtime -->|"checks"| node_security
node_action_runtime -->|"records"| node_storage
node_knowledge_core -->|"reads/writes"| node_storage
node_automation_core -->|"tracks"| node_storage
node_self_evolve -->|"benchmarks"| node_storage
node_swarm_core -->|"state"| node_storage
node_connectivity -->|"delivers"| node_messaging_platforms
node_connectivity -->|"browser"| node_browser_web
node_connectivity -->|"synchronizes"| node_google_services
node_action_runtime -->|"sidecars"| node_bridge_services
node_model_layer -->|"calls"| node_llm_providers

click node_frontend_app "https://github.com/agentark-ai/agentark/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/agentark-ai/agentark/blob/main/frontend/src/api/client.ts"
click node_frontend_panels "https://github.com/agentark-ai/agentark/tree/main/frontend/src/components/pages"
click node_http_core "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/core_api"
click node_http_runtime "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/runtime_api"
click node_http_app "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/app_api"
click node_http_automation "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/automation_api"
click node_http_integrations "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/integration_api"
click node_http_admin "https://github.com/agentark-ai/agentark/tree/main/src/channels/http/admin_api"
click node_agent_loop "https://github.com/agentark-ai/agentark/tree/main/src/core/agent"
click node_model_layer "https://github.com/agentark-ai/agentark/tree/main/src/core/model"
click node_orchestration "https://github.com/agentark-ai/agentark/tree/main/src/core/orchestration"
click node_automation_core "https://github.com/agentark-ai/agentark/tree/main/src/core/automation"
click node_knowledge_core "https://github.com/agentark-ai/agentark/tree/main/src/core/knowledge"
click node_self_evolve "https://github.com/agentark-ai/agentark/tree/main/src/core/self_evolve"
click node_swarm_core "https://github.com/agentark-ai/agentark/tree/main/src/core/swarm"
click node_action_runtime "https://github.com/agentark-ai/agentark/tree/main/src/runtime/action_runtime"
click node_security "https://github.com/agentark-ai/agentark/tree/main/src/security"
click node_storage "https://github.com/agentark-ai/agentark/tree/main/src/storage"
click node_connectivity "https://github.com/agentark-ai/agentark/tree/main/src/core/connectivity"
click node_companion_clients "https://github.com/agentark-ai/agentark/tree/main/clients/companion"
click node_messaging_platforms "https://github.com/agentark-ai/agentark/tree/main/src/channels/messaging"
click node_browser_web "https://github.com/agentark-ai/agentark/tree/main/src/integrations/browser"
click node_google_services "https://github.com/agentark-ai/agentark/tree/main/src/integrations/google"
click node_bridge_services "https://github.com/agentark-ai/agentark/tree/main/bridges"

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_app,node_frontend_api,node_frontend_panels toneBlue
class node_http_core,node_http_runtime,node_http_app,node_http_automation,node_http_integrations,node_http_admin toneAmber
class node_agent_loop,node_model_layer,node_orchestration,node_automation_core,node_knowledge_core,node_self_evolve,node_swarm_core toneMint
class node_action_runtime,node_security,node_storage,node_connectivity toneRose
class node_companion_clients,node_messaging_platforms,node_llm_providers,node_browser_web,node_google_services,node_bridge_services toneIndigo
```

## Components

### Frontend

React/Vite operator console and client layer

- [Mission Control](https://github.com/agentark-ai/agentark/blob/main/frontend/src/App.tsx): React UI · Main operator console for chat, memory, settings, observability, and evolution · `frontend/src/App.tsx`
- [API client](https://github.com/agentark-ai/agentark/blob/main/frontend/src/api/client.ts): TS client · Frontend backend client used by all major surfaces · `frontend/src/api/client.ts`
- [UI panels](https://github.com/agentark-ai/agentark/tree/main/frontend/src/components/pages): Feature pages · Chat, tasks, memory, reflect, sentinel, evolve, pulse, integrations, and analytics surfaces · `frontend/src/components/pages`

### Rust control plane

HTTP APIs, orchestration, and backend services

- [Core APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/core_api): HTTP control · Chat, conversation, auth, middleware, notifications, and core server utilities · `src/channels/http/core_api`
- [Runtime APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/runtime_api): HTTP control · Memory, documents, settings, browser profiles, model failover, and voice/runtime control · `src/channels/http/runtime_api`
- [App APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/app_api): HTTP control · App serving, companion control, suggestions, UI control, ArkOrbit, and ArkPulse · `src/channels/http/app_api`
- [Automation APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/automation_api): HTTP control · Automation, autonomy, reflect, evolution, swarm, and sentinel surfaces · `src/channels/http/automation_api`
- [Integration APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/integration_api): HTTP control · Integrations, gateway ops, sync, monitoring, webhooks, and custom messaging channels · `src/channels/http/integration_api`
- [Admin APIs](https://github.com/agentark-ai/agentark/tree/main/src/channels/http/admin_api): HTTP control · Security, profiles, secrets, sender verification, and locked control · `src/channels/http/admin_api`

### Core domains

Agent, memory, automation, model, and learning logic

- [Agent loop](https://github.com/agentark-ai/agentark/tree/main/src/core/agent): Reasoning engine · Conversation handling, prompt spine, runtime execution, and operations · `src/core/agent`
- [Model layer](https://github.com/agentark-ai/agentark/tree/main/src/core/model): LLM abstraction · Provider access, context budgeting, failover, prompt policy, and sanitization · `src/core/model`
- [Orchestration](https://github.com/agentark-ai/agentark/tree/main/src/core/orchestration): Planner/executor · Action catalog, planning, pipeline coordination, and execution control · `src/core/orchestration`
- [Automation](https://github.com/agentark-ai/agentark/tree/main/src/core/automation): Background work · Tasks, watchers, runs, autonomy, and background sessions · `src/core/automation`
- [Knowledge](https://github.com/agentark-ai/agentark/tree/main/src/core/knowledge): Memory/search · Embeddings, document search, learning, deduplication, and memory schema · `src/core/knowledge`
- [Self-evolve](https://github.com/agentark-ai/agentark/tree/main/src/core/self_evolve): Learning loop · Opportunities, benchmarks, prompt and routing evolution, gates, and self-tuning · `src/core/self_evolve`
- [Swarm](https://github.com/agentark-ai/agentark/tree/main/src/core/swarm): Multi-agent · Specialist agents, coordination bus, and shared swarm state · `src/core/swarm`

### Execution and trust

Sandboxes, security boundaries, and persistence

- [Action runtime](https://github.com/agentark-ai/agentark/tree/main/src/runtime/action_runtime): Sandbox executor · Native, CLI, code, WASM/docker, web, and governed action execution · `src/runtime/action_runtime`
- [Security](https://github.com/agentark-ai/agentark/tree/main/src/security): Trust boundary · Abuse tracking, privacy normalization, action guards, tool validation, and review policies · `src/security`
- [Storage](https://github.com/agentark-ai/agentark/tree/main/src/storage): Local persistence · Encrypted storage, entities, repositories, audit logs, memory, tasks, traces, and usage · `src/storage`
- [Connectivity](https://github.com/agentark-ai/agentark/tree/main/src/core/connectivity): Channels and gateways · Browser, messaging, email delivery, sender verification, gateway, and integration sync · `src/core/connectivity`

### External boundaries

Outside systems and companion endpoints

- [Companions](https://github.com/agentark-ai/agentark/tree/main/clients/companion): Mobile/desktop clients · Android, iOS, desktop, and custom-device clients speaking the companion protocol · `clients/companion`
- [Messaging platforms](https://github.com/agentark-ai/agentark/tree/main/src/channels/messaging): External channels · Slack, Telegram, WhatsApp, Teams, Signal, Matrix, and related outbound platforms · `src/channels/messaging`
- **LLM providers**: External model APIs · Remote or local model backends used through the model abstraction
- [Browser/web](https://github.com/agentark-ai/agentark/tree/main/src/integrations/browser): External automation · Web access, browser sessions, and browser automation side effects · `src/integrations/browser`
- [Google services](https://github.com/agentark-ai/agentark/tree/main/src/integrations/google): External SaaS · Workspace, calendar, Gmail, analytics, search, and places integrations · `src/integrations/google`
- [Sidecar bridges](https://github.com/agentark-ai/agentark/tree/main/bridges): Auxiliary services · Playwright, voice, WhatsApp bridge, and GEPA optimizer sidecars · `bridges`

## Connections

- Mission Control → API client: calls · UI uses the shared API client for backend communication
- UI panels → API client: loads data · Feature panels fetch and mutate backend state
- API client → Core APIs: chat/control · Primary UI traffic enters the core HTTP API group
- API client → Runtime APIs: runtime state · Settings, memory, browser, and voice control flows
- API client → App APIs: app surfaces · Mission Control and companion/app panels use app APIs
- API client → Automation APIs: supervision · Autonomy, reflect, evolve, and swarm panels query automation APIs
- API client → Integration APIs: connectors · Integrations and webhooks are managed through integration APIs
- API client → Admin APIs: admin · Security and secrets surfaces use admin APIs
- Core APIs → Agent loop: drives · Conversation and control endpoints invoke the agent loop
- Runtime APIs → Knowledge: memory · Runtime endpoints expose memory and document retrieval
- Runtime APIs → Model layer: model control · Model settings and failover are mediated through runtime APIs
- App APIs → Companions: pairing/control · Companion device control is surfaced through app APIs
- Automation APIs → Automation: supervises · Automation and autonomy endpoints manage background work
- Automation APIs → Self-evolve: evolution · Reflect/evolve endpoints feed the learning subsystem
- Integration APIs → Connectivity: routes · Integration and gateway APIs map to connectivity services
- Admin APIs → Security: enforces · Administrative control is constrained by trust and security policy
- Agent loop → Model layer: queries · The agent loop builds prompts and calls the model abstraction
- Agent loop → Orchestration: plans · Tooling and task execution are coordinated through orchestration
- Agent loop → Knowledge: retrieves · Conversation state and memory retrieval inform reasoning
- Orchestration → Action runtime: executes · Planned actions are validated and run in isolated runtimes
- Action runtime → Security: checks · Execution is gated by authorization, privacy, and review policies
- Action runtime → Storage: records · Runs, proofs, traces, and artifacts are persisted for auditability
- Knowledge → Storage: reads/writes · Memory, documents, and learning data are persisted locally
- Automation → Storage: tracks · Background sessions, tasks, runs, and watchers are stored
- Self-evolve → Storage: benchmarks · Opportunities, evals, and ledgers use stored history and traces
- Swarm → Storage: state · Swarm coordination and agent state are persisted
- Connectivity → Messaging platforms: delivers · Outbound messaging connectors bridge to external platforms
- Connectivity → Browser/web: browser · Browser sessions and web automation cross the web boundary
- Connectivity → Google services: synchronizes · Google integrations connect productivity and analytics services
- Action runtime → Sidecar bridges: sidecars · Heavyweight browser, voice, and optimizer capabilities live in bridges
- Model layer → LLM providers: calls · LLM access is abstracted behind provider integrations
