# agentconnect-md/agentconnect architecture

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

- Interactive diagram: https://gitdiagram.com/agentconnect-md/agentconnect
- Repository: https://github.com/agentconnect-md/agentconnect

## Overview

#### Purpose and topology
AgentConnect is a daemon-centric, self-hostable platform for running ACP-compatible AI agents from collaboration channels, GitHub events, webhooks, schedules, and webchat. It separates a management/control plane from edge execution so agent workspaces, runtime credentials, live messages, and sessions remain in the operator’s environment. Core deployment definitions are `compose.yaml`, `deploy/k8s/30-deployment.yaml`, and `charts/operator/templates/operator-deployment.yaml`.

#### User and operational entry points
The stable `agentconnect` CLI installs, starts, recovers, upgrades, and delegates to the local daemon; its command entry is `packages/cli/src/index.ts`, with daemon service lifecycle in `packages/cli/src/service/index.ts`. The daemon executable begins at `packages/daemon/src/index.ts` and assembles the long-running edge process in `packages/daemon/src/daemon.ts`. The management console is a Next.js application rooted at `packages/web/src/app/layout.tsx`; organization-scoped console routes are under `packages/web/src/app/(app)/[slug]`.

#### Control Plane: authoritative coordination boundary
The Control Plane owns organizations, identities, agent configuration, placement, access policy, integrations, audit/usage metadata, and API/WebSocket interfaces. HTTP application/server composition is in `packages/control-plane/src/app.ts` and `packages/control-plane/src/http/server.ts`; daemon gateway handling is in `packages/control-plane/src/ws/gateway.ts`. It does not ordinarily persist message bodies or ACP streams: it coordinates and pushes configuration to daemons.

#### Persistence, identity, and secrets
PostgreSQL/Prisma backs multi-tenant coordination state and repositories, modeled in `packages/control-plane/prisma/schema.prisma` and accessed through `packages/control-plane/src/persistence/prisma.ts`. HTTP auth and organization scoping form the main request boundary in `packages/control-plane/src/http/plugins/auth.ts` and `packages/control-plane/src/http/org-scope.ts`. Secret handling is explicitly separated through encrypted/brokered providers in `packages/control-plane/src/secrets/secretsBroker.ts` and `packages/control-plane/src/secrets/vault-transit.ts`; Logto is supported for hosted/local authentication via `compose.logto.yaml`.

#### Daemon execution and session pipeline
A daemon maintains Control Plane connectivity, reconciles assigned agents/configuration, receives platform events, selects an agent/session, and runs the configured runtime locally or in Kubernetes. Session ownership and transcript/turn handling live in `packages/daemon/src/session/session-manager.ts` and `packages/daemon/src/session/transcript-recorder.ts`. ACP runtime launch/sandbox boundaries are implemented in `packages/daemon/src/acp/acp-host.ts` and `packages/daemon/src/acp/runtime-launch.ts`; runtime selection, credentials, and model discovery are in `packages/daemon/src/runtimes/registry.ts`.

#### Messaging, routing, and integration data plane
Platform adapters normalize and render Slack, Telegram, Discord, Feishu, and GitHub traffic, with shared dispatch contracts in `packages/daemon/src/platforms/registry.ts` and routing rules in `packages/daemon/src/router/routing-table.ts`. The optional Relay accepts callback/webchat ingress and forwards it to the owning daemon without durable message storage; its server is `packages/relay/src/server.ts`, ingress manager is `packages/relay/src/relay-ingress-manager.ts`, and webchat routing is `packages/relay/src/webchat-router.ts`. Shared daemon–relay–Control Plane frame contracts are defined in `packages/protocol/src/index.ts` and `packages/protocol/src/frames`.

#### Agent capabilities and infrastructure extensions
Agents receive per-agent workspace, Git policy, skills, MCP tools, memory, runtime, and sandbox policy. Workspace/Git execution is bounded by `packages/daemon/src/workspace/workspace-manager.ts` and `packages/daemon/src/workspace/git-origin-policy.ts`; MCP injection/control is in `packages/daemon/src/mcp/bridge.ts`. Memory supports native, managed, and external providers through `packages/daemon/src/agents/memory-provider.ts`, with Mem0 Cloud/OSS implemented by `packages/memory-plugin-mem0/src/server.ts`. Kubernetes placement/runtime-pool support spans `packages/daemon/src/k8s/runtime-plane.ts` and the controller in `packages/operator/src/controller.ts`.

Main entry points: [`packages/daemon/src/daemon.ts`](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/daemon.ts) (Edge daemon), [`packages/control-plane/src/http/server.ts`](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/http/server.ts) (Control Plane API), [`packages/daemon/src/runtimes/registry.ts`](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/runtimes/registry.ts) (Runtime registry), [`packages/daemon/src/acp/acp-host.ts`](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/acp/acp-host.ts) (ACP host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_cli["agentconnect CLI<br/>[index.ts]"]
  node_cli_service["Daemon service lifecycle<br/>service manager<br/>[index.ts]"]
end

subgraph group_control["Control Plane"]
  node_control_api["Control Plane API<br/>HTTP server<br/>[server.ts]"]
  node_auth_scope["Auth &amp; org scope<br/>request boundary<br/>[auth.ts]"]
  node_control_gateway["Daemon gateway<br/>WebSocket gateway<br/>[gateway.ts]"]
  node_coordination_store[("Coordination store<br/>PostgreSQL / Prisma<br/>[schema.prisma]")]
  node_secrets["Secrets broker<br/>secret provider<br/>[secretsBroker.ts]"]
end

subgraph group_edge["Edge Execution"]
  node_daemon["Edge daemon<br/>long-running process<br/>[daemon.ts]"]
  node_routing["Agent routing<br/>routing table<br/>[routing-table.ts]"]
  node_sessions["Session manager<br/>session pipeline<br/>[session-manager.ts]"]
  node_runtime_registry["Runtime registry<br/>runtime selection<br/>[registry.ts]"]
  node_acp_host["ACP host<br/>runtime sandbox<br/>[acp-host.ts]"]
  node_workspace["Workspace &amp; Git policy<br/>workspace boundary"]
  node_mcp["MCP bridge<br/>tool injection<br/>[bridge.ts]"]
end

subgraph group_ingress["Ingress &amp; Clients"]
  node_console["Management Console<br/>Next.js app<br/>[layout.tsx]"]
  node_platforms["Collaboration platforms<br/>external channels<br/>[registry.ts]"]
  node_relay["Relay ingress<br/>stateless relay<br/>[server.ts]"]
  node_webchat_router["Webchat routing<br/>ingress routing<br/>[webchat-router.ts]"]
end

subgraph group_extensions["Extensions &amp; Infrastructure"]
  node_memory["Agent memory<br/>memory provider<br/>[memory-provider.ts]"]
  node_mem0["Mem0 provider<br/>memory plugin<br/>[server.ts]"]
  node_k8s_runtime["Kubernetes runtime plane<br/>runtime placement<br/>[runtime-plane.ts]"]
  node_operator["Kubernetes operator<br/>controller<br/>[controller.ts]"]
  node_protocol["Shared frame protocol<br/>protocol contracts<br/>[index.ts]"]
end

node_cli -->|"manages"| node_cli_service
node_cli_service -->|"starts / recovers"| node_daemon
node_console -->|"management API"| node_control_api
node_control_api -->|"applies"| node_auth_scope
node_auth_scope -->|"scoped access"| node_coordination_store
node_control_api -->|"coordination state"| node_coordination_store
node_control_api -->|"brokers credentials"| node_secrets
node_daemon -->|"persistent connection"| node_control_gateway
node_control_gateway -->|"assignments / config"| node_coordination_store
node_platforms -->|"adapter events"| node_daemon
node_relay -->|"webchat ingress"| node_webchat_router
node_webchat_router -->|"forwards to owner"| node_daemon
node_daemon -->|"dispatches events"| node_routing
node_routing -->|"agent session"| node_sessions
node_sessions -->|"selects runtime"| node_runtime_registry
node_runtime_registry -->|"launches"| node_acp_host
node_acp_host -->|"agent workspace"| node_workspace
node_acp_host -->|"tool access"| node_mcp
node_acp_host -->|"memory access"| node_memory
node_memory -.->|"external provider"| node_mem0
node_runtime_registry -.->|"runtime credentials"| node_secrets
node_runtime_registry -.->|"Kubernetes placement"| node_k8s_runtime
node_k8s_runtime -->|"runtime resources"| node_operator
node_daemon -.->|"uses frames"| node_protocol
node_relay -.->|"uses frames"| node_protocol
node_control_gateway -.->|"uses frames"| node_protocol

click node_cli "https://github.com/agentconnect-md/agentconnect/blob/main/packages/cli/src/index.ts"
click node_cli_service "https://github.com/agentconnect-md/agentconnect/blob/main/packages/cli/src/service/index.ts"
click node_console "https://github.com/agentconnect-md/agentconnect/blob/main/packages/web/src/app/layout.tsx"
click node_platforms "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/platforms/registry.ts"
click node_relay "https://github.com/agentconnect-md/agentconnect/blob/main/packages/relay/src/server.ts"
click node_webchat_router "https://github.com/agentconnect-md/agentconnect/blob/main/packages/relay/src/webchat-router.ts"
click node_control_api "https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/http/server.ts"
click node_auth_scope "https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/http/plugins/auth.ts"
click node_control_gateway "https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/ws/gateway.ts"
click node_coordination_store "https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/prisma/schema.prisma"
click node_secrets "https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/secrets/secretsBroker.ts"
click node_daemon "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/daemon.ts"
click node_routing "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/router/routing-table.ts"
click node_sessions "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/session/session-manager.ts"
click node_runtime_registry "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/runtimes/registry.ts"
click node_acp_host "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/acp/acp-host.ts"
click node_workspace "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/workspace/workspace-manager.ts"
click node_mcp "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/mcp/bridge.ts"
click node_memory "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/agents/memory-provider.ts"
click node_mem0 "https://github.com/agentconnect-md/agentconnect/blob/main/packages/memory-plugin-mem0/src/server.ts"
click node_k8s_runtime "https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/k8s/runtime-plane.ts"
click node_operator "https://github.com/agentconnect-md/agentconnect/blob/main/packages/operator/src/controller.ts"
click node_protocol "https://github.com/agentconnect-md/agentconnect/blob/main/packages/protocol/src/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_cli,node_cli_service toneBlue
class node_control_api,node_auth_scope,node_control_gateway,node_coordination_store,node_secrets toneAmber
class node_daemon,node_routing,node_sessions,node_runtime_registry,node_acp_host,node_workspace,node_mcp toneMint
class node_console,node_platforms,node_relay,node_webchat_router toneRose
class node_memory,node_mem0,node_k8s_runtime,node_operator,node_protocol toneIndigo
```

## Components

### Entry Points

- [agentconnect CLI](https://github.com/agentconnect-md/agentconnect/blob/main/packages/cli/src/index.ts): CLI · Installs and delegates lifecycle operations to the local daemon. · `packages/cli/src/index.ts`
- [Daemon service lifecycle](https://github.com/agentconnect-md/agentconnect/blob/main/packages/cli/src/service/index.ts): service manager · `packages/cli/src/service/index.ts`

### Control Plane

Authoritative coordination and policy boundary.

- [Control Plane API](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/http/server.ts): HTTP server · Management API and application composition. · `packages/control-plane/src/http/server.ts`
- [Auth & org scope](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/http/plugins/auth.ts): request boundary · Authenticates requests and establishes tenant scope. · `packages/control-plane/src/http/plugins/auth.ts`
- [Daemon gateway](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/ws/gateway.ts): WebSocket gateway · Coordinates connected daemons and configuration delivery. · `packages/control-plane/src/ws/gateway.ts`
- [Coordination store](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/prisma/schema.prisma): PostgreSQL / Prisma · Multi-tenant organizations, agents, placement, policy, and audit metadata. · `packages/control-plane/prisma/schema.prisma`
- [Secrets broker](https://github.com/agentconnect-md/agentconnect/blob/main/packages/control-plane/src/secrets/secretsBroker.ts): secret provider · Encrypted and brokered runtime credentials. · `packages/control-plane/src/secrets/secretsBroker.ts`

### Edge Execution

Operator-local daemon execution and agent data plane.

- [Edge daemon](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/daemon.ts): long-running process · Reconciles assignments and runs agent work in the operator environment. · `packages/daemon/src/daemon.ts`
- [Agent routing](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/router/routing-table.ts): routing table · Selects agent and session for normalized events. · `packages/daemon/src/router/routing-table.ts`
- [Session manager](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/session/session-manager.ts): session pipeline · Owns sessions, turns, and transcripts locally. · `packages/daemon/src/session/session-manager.ts`
- [Runtime registry](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/runtimes/registry.ts): runtime selection · Selects runtimes, credentials, and models. · `packages/daemon/src/runtimes/registry.ts`
- [ACP host](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/acp/acp-host.ts): runtime sandbox · Launches and hosts ACP-compatible agent runtimes. · `packages/daemon/src/acp/acp-host.ts`
- [Workspace & Git policy](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/workspace/workspace-manager.ts): workspace boundary · Provides per-agent workspaces with bounded Git access. · `packages/daemon/src/workspace/workspace-manager.ts`
- [MCP bridge](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/mcp/bridge.ts): tool injection · `packages/daemon/src/mcp/bridge.ts`

### Ingress & Clients

- [Management Console](https://github.com/agentconnect-md/agentconnect/blob/main/packages/web/src/app/layout.tsx): Next.js app · Organization-scoped management UI. · `packages/web/src/app/layout.tsx`
- [Collaboration platforms](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/platforms/registry.ts): external channels · Slack, Telegram, Discord, Feishu, and GitHub events. · `packages/daemon/src/platforms/registry.ts`
- [Relay ingress](https://github.com/agentconnect-md/agentconnect/blob/main/packages/relay/src/server.ts): stateless relay · Forwards callback and webchat ingress to the owning daemon. · `packages/relay/src/server.ts`
- [Webchat routing](https://github.com/agentconnect-md/agentconnect/blob/main/packages/relay/src/webchat-router.ts): ingress routing · `packages/relay/src/webchat-router.ts`

### Extensions & Infrastructure

- [Agent memory](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/agents/memory-provider.ts): memory provider · Supports native, managed, and external memory providers. · `packages/daemon/src/agents/memory-provider.ts`
- [Mem0 provider](https://github.com/agentconnect-md/agentconnect/blob/main/packages/memory-plugin-mem0/src/server.ts): memory plugin · Mem0 Cloud and OSS integration. · `packages/memory-plugin-mem0/src/server.ts`
- [Kubernetes runtime plane](https://github.com/agentconnect-md/agentconnect/blob/main/packages/daemon/src/k8s/runtime-plane.ts): runtime placement · Supports Kubernetes runtime pools. · `packages/daemon/src/k8s/runtime-plane.ts`
- [Kubernetes operator](https://github.com/agentconnect-md/agentconnect/blob/main/packages/operator/src/controller.ts): controller · Reconciles Kubernetes runtime infrastructure. · `packages/operator/src/controller.ts`
- [Shared frame protocol](https://github.com/agentconnect-md/agentconnect/blob/main/packages/protocol/src/index.ts): protocol contracts · Daemon, Relay, and Control Plane frame contracts. · `packages/protocol/src/index.ts`

## Connections

- agentconnect CLI → Daemon service lifecycle: manages
- Daemon service lifecycle → Edge daemon: starts / recovers
- Management Console → Control Plane API: management API
- Control Plane API → Auth & org scope: applies
- Auth & org scope → Coordination store: scoped access
- Control Plane API → Coordination store: coordination state
- Control Plane API → Secrets broker: brokers credentials
- Edge daemon → Daemon gateway: persistent connection
- Daemon gateway → Coordination store: assignments / config
- Collaboration platforms → Edge daemon: adapter events
- Relay ingress → Webchat routing: webchat ingress
- Webchat routing → Edge daemon: forwards to owner
- Edge daemon → Agent routing: dispatches events
- Agent routing → Session manager: agent session
- Session manager → Runtime registry: selects runtime
- Runtime registry → ACP host: launches
- ACP host → Workspace & Git policy: agent workspace
- ACP host → MCP bridge: tool access
- ACP host → Agent memory: memory access
- Agent memory → Mem0 provider: external provider
- Runtime registry → Secrets broker: runtime credentials
- Runtime registry → Kubernetes runtime plane: Kubernetes placement
- Kubernetes runtime plane → Kubernetes operator: runtime resources
- Edge daemon → Shared frame protocol: uses frames
- Relay ingress → Shared frame protocol: uses frames
- Daemon gateway → Shared frame protocol: uses frames