# zeyuw/flow-agent architecture

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

## Overview

Flow Agent is a multi-channel assistant service. A user message enters through a channel adapter, is handled as a passive conversational turn, and produces a response for outbound delivery. The turn can use the shared agent loop, model and tool capabilities, session history, and retrieved memory. Separate runtime branches support proactive checks, scheduled automation, delegated agents, and management through a local API and dashboard. The README documents these broader capabilities; some subsystem wiring is represented only at directory level because its implementation was not sampled.

Main entry points: [`backend/src/application/passive/app/pipeline.py`](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/passive/app/pipeline.py) (Passive Turn), [`backend/src/interfaces/channels`](https://github.com/zeyuw/flow-agent/tree/main/backend/src/interfaces/channels) (Channel Adapters), [`backend/src/application/agent/app/loop.py`](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/agent/app/loop.py) (Agent Loop), [`backend/src/application/capabilities/tools/registry.py`](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/tools/registry.py) (Tool Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service and Channels"]
  node_bootstrap["Service Lifecycle<br/>[main.py]"]
  node_channels["Channel Adapters"]
end

subgraph group_conversation["Conversation Runtime"]
  node_passive["Passive Turn<br/>[pipeline.py]"]
  node_agent["Agent Loop<br/>[loop.py]"]
  node_sessions[("Session History<br/>[session_manager.py]")]
  node_memory["Memory Retrieval<br/>[engine.py]"]
end

subgraph group_extensions["Agent Capabilities"]
  node_model["LLM Client<br/>[client.py]"]
  node_tools["Tool Registry<br/>[registry.py]"]
  node_plugins["Plugin Runtime<br/>[plugin_runtime.py]"]
  node_mcp["MCP Connectors"]
  node_skills["Skill Catalog"]
end

subgraph group_background["Background Work"]
  node_proactive["Proactive Pipeline<br/>[pipeline.py]"]
  node_drift["Drift Execution<br/>[drift_pipeline.py]"]
  node_automation["Automation Runtime<br/>[runtime.py]"]
  node_schedule["Schedule Runtime<br/>[runtime.py]"]
  node_delegation["Subagent Manager<br/>[manager.py]"]
  node_taskstore[("Task Store<br/>[store.py]")]
end

subgraph group_console["Management Console"]
  node_admin["Admin API<br/>[router.py]"]
  node_capquery["Capability Query"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_api["API Client<br/>[client.ts]"]
end

node_user(("User"))

node_bootstrap -->|"starts"| node_channels
node_user -->|"sends message"| node_channels
node_channels -->|"routes inbound"| node_passive
node_passive -->|"runs reasoning"| node_agent
node_passive -->|"reads/writes history"| node_sessions
node_passive -->|"retrieves context"| node_memory
node_agent -->|"requests completion"| node_model
node_agent -->|"dispatches tools"| node_tools
node_tools -.->|"uses extensions"| node_plugins
node_tools -.->|"invokes connector tools"| node_mcp
node_skills -.->|"provides skills"| node_agent
node_passive -->|"delivers response"| node_channels
node_proactive -.->|"runs fallback"| node_drift
node_proactive -->|"delivers message"| node_channels
node_automation -.->|"delegates task"| node_delegation
node_delegation -->|"persists task"| node_taskstore
node_user -->|"manages service"| node_dashboard
node_dashboard -->|"calls API"| node_api
node_api -->|"sends requests"| node_admin
node_admin -->|"queries capabilities"| node_capquery
node_capquery -->|"lists skills"| node_skills
node_capquery -->|"lists connectors"| node_mcp

click node_bootstrap "https://github.com/zeyuw/flow-agent/blob/main/backend/src/bootstrap/main.py"
click node_channels "https://github.com/zeyuw/flow-agent/tree/main/backend/src/interfaces/channels"
click node_passive "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/passive/app/pipeline.py"
click node_agent "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/agent/app/loop.py"
click node_sessions "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/passive/infra/session_manager.py"
click node_memory "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/memory/app/engine.py"
click node_model "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/llm/client.py"
click node_tools "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/tools/registry.py"
click node_plugins "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/plugins/plugin_runtime.py"
click node_mcp "https://github.com/zeyuw/flow-agent/tree/main/backend/src/application/capabilities/mcp"
click node_skills "https://github.com/zeyuw/flow-agent/tree/main/backend/src/application/capabilities/skills"
click node_proactive "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/proactive/app/pipeline.py"
click node_drift "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/proactive/app/drift_pipeline.py"
click node_automation "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/automation/app/runtime.py"
click node_schedule "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/schedule/app/runtime.py"
click node_delegation "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/delegation/app/manager.py"
click node_taskstore "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/delegation/infra/store.py"
click node_admin "https://github.com/zeyuw/flow-agent/blob/main/backend/src/interfaces/admin/router.py"
click node_capquery "https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/app/capability_query.py"
click node_dashboard "https://github.com/zeyuw/flow-agent/blob/main/frontend/src/app/page.tsx"
click node_api "https://github.com/zeyuw/flow-agent/blob/main/frontend/src/lib/api/client.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_bootstrap,node_channels,node_user toneBlue
class node_passive,node_agent,node_sessions,node_memory toneAmber
class node_model,node_tools,node_plugins,node_mcp,node_skills toneMint
class node_proactive,node_drift,node_automation,node_schedule,node_delegation,node_taskstore toneRose
class node_admin,node_capquery,node_dashboard,node_api toneIndigo
```

## Components

### Service and Channels

- [Service Lifecycle](https://github.com/zeyuw/flow-agent/blob/main/backend/src/bootstrap/main.py): `backend/src/bootstrap/main.py`
- [Channel Adapters](https://github.com/zeyuw/flow-agent/tree/main/backend/src/interfaces/channels): `backend/src/interfaces/channels`

### Conversation Runtime

- [Passive Turn](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/passive/app/pipeline.py): `backend/src/application/passive/app/pipeline.py`
- [Agent Loop](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/agent/app/loop.py): `backend/src/application/agent/app/loop.py`
- [Session History](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/passive/infra/session_manager.py): `backend/src/application/passive/infra/session_manager.py`
- [Memory Retrieval](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/memory/app/engine.py): `backend/src/application/memory/app/engine.py`

### Agent Capabilities

- [LLM Client](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/llm/client.py): `backend/src/application/capabilities/llm/client.py`
- [Tool Registry](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/tools/registry.py): `backend/src/application/capabilities/tools/registry.py`
- [Plugin Runtime](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/plugins/plugin_runtime.py): `backend/src/application/capabilities/plugins/plugin_runtime.py`
- [MCP Connectors](https://github.com/zeyuw/flow-agent/tree/main/backend/src/application/capabilities/mcp): `backend/src/application/capabilities/mcp`
- [Skill Catalog](https://github.com/zeyuw/flow-agent/tree/main/backend/src/application/capabilities/skills): `backend/src/application/capabilities/skills`

### Background Work

- [Proactive Pipeline](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/proactive/app/pipeline.py): `backend/src/application/proactive/app/pipeline.py`
- [Drift Execution](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/proactive/app/drift_pipeline.py): `backend/src/application/proactive/app/drift_pipeline.py`
- [Automation Runtime](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/automation/app/runtime.py): `backend/src/application/automation/app/runtime.py`
- [Schedule Runtime](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/schedule/app/runtime.py): `backend/src/application/schedule/app/runtime.py`
- [Subagent Manager](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/delegation/app/manager.py): `backend/src/application/delegation/app/manager.py`
- [Task Store](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/delegation/infra/store.py): `backend/src/application/delegation/infra/store.py`

### Management Console

- [Admin API](https://github.com/zeyuw/flow-agent/blob/main/backend/src/interfaces/admin/router.py): `backend/src/interfaces/admin/router.py`
- [Capability Query](https://github.com/zeyuw/flow-agent/blob/main/backend/src/application/capabilities/app/capability_query.py): `backend/src/application/capabilities/app/capability_query.py`
- [Dashboard](https://github.com/zeyuw/flow-agent/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [API Client](https://github.com/zeyuw/flow-agent/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`

### Other components

- **User**

## Connections

- Service Lifecycle → Channel Adapters: starts
- User → Channel Adapters: sends message
- Channel Adapters → Passive Turn: routes inbound
- Passive Turn → Agent Loop: runs reasoning
- Passive Turn → Session History: reads/writes history
- Passive Turn → Memory Retrieval: retrieves context
- Agent Loop → LLM Client: requests completion
- Agent Loop → Tool Registry: dispatches tools
- Tool Registry → Plugin Runtime: uses extensions
- Tool Registry → MCP Connectors: invokes connector tools
- Skill Catalog → Agent Loop: provides skills
- Passive Turn → Channel Adapters: delivers response
- Proactive Pipeline → Drift Execution: runs fallback
- Proactive Pipeline → Channel Adapters: delivers message
- Automation Runtime → Subagent Manager: delegates task
- Subagent Manager → Task Store: persists task
- User → Dashboard: manages service
- Dashboard → API Client: calls API
- API Client → Admin API: sends requests
- Admin API → Capability Query: queries capabilities
- Capability Query → Skill Catalog: lists skills
- Capability Query → MCP Connectors: lists connectors