# evovexai/evoflow architecture

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

- Interactive diagram: https://gitdiagram.com/evovexai/evoflow
- Repository: https://github.com/evovexai/evoflow

## Overview

EvoFlow is a long-running, multi-agent runtime and control plane. Its principal workflow is a user starting a conversation or plan, the runtime coordinating agent work and tools, and progress and results returning through streaming UI or task channels. The README also describes goals, approvals, automation, workspaces and code indexing, knowledge, memory, integrations, and governance. The graph combines documented capabilities with sampled backend relationships; several subsystems are represented at directory level because their implementation was not excerpted.

Main entry points: [`backend/app/gateway`](https://github.com/evovexai/evoflow/tree/main/backend/app/gateway) (Gateway API), [`backend/packages/harness/evoflow/agents/lead_agent`](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/lead_agent) (Lead agent), [`evopanel/src`](https://github.com/evovexai/evoflow/tree/main/evopanel/src) (Desktop interface), [`backend/packages/harness/evoflow/collab`](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/collab) (Agent collaboration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_desktop["Desktop interface"]
  node_turn["Stream turn engine"]
  node_channels["IM channels"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Lead agent"]
  node_goal["Goal runtime"]
  node_middleware["Agent middleware"]
end

subgraph group_work["Task execution"]
  node_collab["Agent collaboration"]
  node_taskqueue["Unattended task pipeline"]
  node_proactive["Proactive engine<br/>[engine.py]"]
  node_scheduler["Scheduler<br/>[engine.py]"]
end

subgraph group_state["State and knowledge"]
  node_session["Chat sessions"]
  node_knowledge["Knowledge pipeline<br/>[pipeline.py]"]
  node_memory["Agent memory"]
  node_taskstore[("Collaboration storage<br/>[storage.py]")]
  node_db[("Application database<br/>[db.py]")]
  node_repositories["Data repositories<br/>[repositories.py]"]
end

subgraph group_control["Control plane"]
  node_gateway["Gateway API"]
  node_governance["Governance and observability"]
  node_eval["Evaluation engine<br/>[eval_engine.py]"]
end

node_user(("User"))

node_user -->|"starts work"| node_desktop
node_desktop -->|"submits requests"| node_gateway
node_gateway -.->|"manages sessions"| node_session
node_gateway -.->|"starts agent runs"| node_agent
node_agent -.->|"runs through"| node_middleware
node_agent -->|"supports goals"| node_goal
node_agent -->|"delegates tasks"| node_collab
node_taskqueue -->|"authorizes dispatch"| node_collab
node_proactive -->|"reads task state"| node_taskstore
node_collab -->|"stores task data"| node_taskstore
node_taskstore -->|"loads task bundles"| node_repositories
node_repositories -->|"uses SQLite"| node_db
node_agent -->|"retrieves knowledge"| node_knowledge
node_agent -->|"uses memory"| node_memory
node_scheduler -.->|"coordinates work"| node_collab
node_channels -->|"dispatches messages"| node_agent
node_gateway -->|"configures integrations"| node_channels
node_gateway -->|"exposes controls"| node_governance
node_gateway -.->|"provides evaluation"| node_eval
node_gateway -.->|"streams events"| node_turn
node_turn -->|"projects updates"| node_desktop
node_desktop -->|"shows results"| node_user

click node_desktop "https://github.com/evovexai/evoflow/tree/main/evopanel/src"
click node_turn "https://github.com/evovexai/evoflow/blob/main/evopanel/src/react/lib/stream-turn-engine.ts"
click node_gateway "https://github.com/evovexai/evoflow/tree/main/backend/app/gateway"
click node_session "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/chat_session_service.py"
click node_agent "https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/lead_agent"
click node_goal "https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/goal"
click node_middleware "https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/middlewares"
click node_collab "https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/collab"
click node_taskqueue "https://github.com/evovexai/evoflow/blob/main/backend/app/gateway/unattended_task_pipeline.py"
click node_proactive "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/proactive/engine.py"
click node_channels "https://github.com/evovexai/evoflow/tree/main/backend/app/channels"
click node_knowledge "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/knowledge/owned/pipeline.py"
click node_memory "https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/memory"
click node_taskstore "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/collab/storage.py"
click node_db "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/db.py"
click node_repositories "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/repositories.py"
click node_scheduler "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/scheduler/engine.py"
click node_governance "https://github.com/evovexai/evoflow/tree/main/backend/app/gateway/routers"
click node_eval "https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/eval/eval_engine.py"

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_desktop,node_turn,node_channels,node_user toneBlue
class node_agent,node_goal,node_middleware toneAmber
class node_collab,node_taskqueue,node_proactive,node_scheduler toneMint
class node_session,node_knowledge,node_memory,node_taskstore,node_db,node_repositories toneRose
class node_gateway,node_governance,node_eval toneIndigo
```

## Components

### User entry

- [Desktop interface](https://github.com/evovexai/evoflow/tree/main/evopanel/src): `evopanel/src`
- [Stream turn engine](https://github.com/evovexai/evoflow/blob/main/evopanel/src/react/lib/stream-turn-engine.ts): `evopanel/src/react/lib/stream-turn-engine.ts`
- [IM channels](https://github.com/evovexai/evoflow/tree/main/backend/app/channels): `backend/app/channels`

### Agent runtime

- [Lead agent](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/lead_agent): `backend/packages/harness/evoflow/agents/lead_agent`
- [Goal runtime](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/goal): `backend/packages/harness/evoflow/agents/goal`
- [Agent middleware](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/middlewares): `backend/packages/harness/evoflow/agents/middlewares`

### Task execution

- [Agent collaboration](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/collab): `backend/packages/harness/evoflow/collab`
- [Unattended task pipeline](https://github.com/evovexai/evoflow/blob/main/backend/app/gateway/unattended_task_pipeline.py): `backend/app/gateway/unattended_task_pipeline.py`
- [Proactive engine](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/proactive/engine.py): `backend/packages/harness/evoflow/proactive/engine.py`
- [Scheduler](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/scheduler/engine.py): `backend/packages/harness/evoflow/scheduler/engine.py`

### State and knowledge

- [Chat sessions](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/chat_session_service.py): `backend/packages/harness/evoflow/persistence/chat_session_service.py`
- [Knowledge pipeline](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/knowledge/owned/pipeline.py): `backend/packages/harness/evoflow/knowledge/owned/pipeline.py`
- [Agent memory](https://github.com/evovexai/evoflow/tree/main/backend/packages/harness/evoflow/agents/memory): `backend/packages/harness/evoflow/agents/memory`
- [Collaboration storage](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/collab/storage.py): `backend/packages/harness/evoflow/collab/storage.py`
- [Application database](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/db.py): `backend/packages/harness/evoflow/persistence/db.py`
- [Data repositories](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/persistence/repositories.py): `backend/packages/harness/evoflow/persistence/repositories.py`

### Control plane

- [Gateway API](https://github.com/evovexai/evoflow/tree/main/backend/app/gateway): `backend/app/gateway`
- [Governance and observability](https://github.com/evovexai/evoflow/tree/main/backend/app/gateway/routers): `backend/app/gateway/routers`
- [Evaluation engine](https://github.com/evovexai/evoflow/blob/main/backend/packages/harness/evoflow/eval/eval_engine.py): `backend/packages/harness/evoflow/eval/eval_engine.py`

### Other components

- **User**

## Connections

- User → Desktop interface: starts work
- Desktop interface → Gateway API: submits requests
- Gateway API → Chat sessions: manages sessions
- Gateway API → Lead agent: starts agent runs
- Lead agent → Agent middleware: runs through
- Lead agent → Goal runtime: supports goals
- Lead agent → Agent collaboration: delegates tasks
- Unattended task pipeline → Agent collaboration: authorizes dispatch (evidence: `backend/app/gateway/unattended_task_pipeline.py`)
- Proactive engine → Collaboration storage: reads task state (evidence: `backend/packages/harness/evoflow/proactive/engine.py`)
- Agent collaboration → Collaboration storage: stores task data (evidence: `backend/packages/harness/evoflow/collab/storage.py`)
- Collaboration storage → Data repositories: loads task bundles (evidence: `backend/packages/harness/evoflow/collab/storage.py`)
- Data repositories → Application database: uses SQLite (evidence: `backend/packages/harness/evoflow/persistence/repositories.py`)
- Lead agent → Knowledge pipeline: retrieves knowledge
- Lead agent → Agent memory: uses memory
- Scheduler → Agent collaboration: coordinates work
- IM channels → Lead agent: dispatches messages
- Gateway API → IM channels: configures integrations (evidence: `backend/app/channels/services/goal_service.py`)
- Gateway API → Governance and observability: exposes controls (evidence: `backend/app/gateway/routers/apps.py`)
- Gateway API → Evaluation engine: provides evaluation
- Gateway API → Stream turn engine: streams events
- Stream turn engine → Desktop interface: projects updates (evidence: `evopanel/src/react/lib/stream-turn-engine.ts`)
- Desktop interface → User: shows results