# aravindanm20/coflowai architecture

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

- Interactive diagram: https://gitdiagram.com/aravindanm20/coflowai
- Repository: https://github.com/aravindanm20/coflowai

## Overview

CoFlowAi is a Python framework for running agents and workflows under deterministic execution controls. A developer defines an agent or workflow and submits it through the app; workflows are compiled before execution, then the runtime applies policy and state controls while coordinating model calls, tools, context, and approvals. Results can be streamed, checkpointed, resumed, replayed, or forked. The README documents distributed workers, durable stores, and observability; those branches are represented at subsystem level where implementation details were not sampled.

Main entry points: [`coflowai/runtime/runtime.py`](https://github.com/aravindanm20/coflowai/blob/main/coflowai/runtime/runtime.py) (Execution Runtime), [`coflowai/app.py`](https://github.com/aravindanm20/coflowai/blob/main/coflowai/app.py) (Application API), [`coflowai/state/store.py`](https://github.com/aravindanm20/coflowai/blob/main/coflowai/state/store.py) (State and Checkpoints), [`coflowai/agents/agent.py`](https://github.com/aravindanm20/coflowai/blob/main/coflowai/agents/agent.py) (Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Developer API"]
  node_app["Application API<br/>[app.py]"]
  node_agent["Agent<br/>[agent.py]"]
  node_workflow["Workflow<br/>[workflow.py]"]
  node_result["Execution Result<br/>[result.py]"]
end

subgraph group_execution["Execution Control"]
  node_compiler["Workflow Compiler<br/>[compiler.py]"]
  node_runtime["Execution Runtime<br/>[runtime.py]"]
  node_policy["Policy and Budgets<br/>[policy.py]"]
  node_context["Execution Context<br/>[context.py]"]
  node_approval["Human Approval<br/>[approval.py]"]
  node_tool_exec["Tool Execution<br/>[executor.py]"]
  node_tool_registry["Tool Registry<br/>[registry.py]"]
end

subgraph group_reasoning["Agent Reasoning"]
  node_model_gateway["Model Gateway<br/>[gateway.py]"]
  node_model_registry["Model Registry<br/>[registry.py]"]
  node_providers["Model Providers"]
  node_context_builder["Context Builder<br/>[builder.py]"]
  node_memory["Memory<br/>[base.py]"]
end

subgraph group_durability["Events and Durability"]
  node_events["Event Engine<br/>[event.py]"]
  node_state[("State and Checkpoints<br/>[store.py]")]
  node_persistence[("Persistence Adapters<br/>[sqlite.py]")]
  node_replay["Replay and Fork<br/>[replay.py]"]
end

subgraph group_operations["Operations"]
  node_observability["Observability<br/>[logger.py]"]
  node_distributed["Distributed Workers<br/>[worker.py]"]
  node_plugins["Plugin Loading<br/>[loader.py]"]
end

node_developer(("Developer / Caller"))

node_developer -->|"submits execution"| node_app
node_app -->|"runs executable"| node_runtime
node_app -->|"configures models"| node_model_registry
node_app -->|"configures tools"| node_tool_registry
node_app -->|"configures state"| node_state
node_app -->|"configures events"| node_events
node_workflow -->|"compiles graph"| node_compiler
node_runtime -->|"enforces limits"| node_policy
node_runtime -->|"creates context"| node_context
node_runtime -->|"saves checkpoints"| node_state
node_runtime -->|"records execution"| node_events
node_runtime -->|"handles decisions"| node_approval
node_runtime -->|"returns result"| node_result
node_runtime -->|"emits telemetry"| node_observability
node_workflow -->|"adds approval gate"| node_approval
node_agent -->|"builds prompt context"| node_context_builder
node_agent -.->|"requests model"| node_model_gateway
node_agent -.->|"dispatches tool calls"| node_tool_exec
node_agent -.->|"uses memory"| node_memory
node_tool_exec -->|"resolves tools"| node_tool_registry
node_model_gateway -->|"resolves provider"| node_model_registry
node_model_gateway -.->|"calls adapter"| node_providers
node_context -->|"checks budgets"| node_policy
node_context -->|"emits events"| node_events
node_state -.->|"persisted by adapters"| node_persistence
node_replay -.->|"loads checkpoints"| node_state
node_distributed -->|"executes jobs"| node_runtime
node_distributed -->|"uses checkpoints"| node_state
node_app -->|"loads plugins"| node_plugins
node_app -->|"returns execution"| node_result

click node_app "https://github.com/aravindanm20/coflowai/blob/main/coflowai/app.py"
click node_agent "https://github.com/aravindanm20/coflowai/blob/main/coflowai/agents/agent.py"
click node_workflow "https://github.com/aravindanm20/coflowai/blob/main/coflowai/workflows/workflow.py"
click node_compiler "https://github.com/aravindanm20/coflowai/blob/main/coflowai/workflows/compiler.py"
click node_runtime "https://github.com/aravindanm20/coflowai/blob/main/coflowai/runtime/runtime.py"
click node_policy "https://github.com/aravindanm20/coflowai/blob/main/coflowai/policies/policy.py"
click node_context "https://github.com/aravindanm20/coflowai/blob/main/coflowai/core/context.py"
click node_approval "https://github.com/aravindanm20/coflowai/blob/main/coflowai/approvals/approval.py"
click node_tool_exec "https://github.com/aravindanm20/coflowai/blob/main/coflowai/tools/executor.py"
click node_tool_registry "https://github.com/aravindanm20/coflowai/blob/main/coflowai/tools/registry.py"
click node_model_gateway "https://github.com/aravindanm20/coflowai/blob/main/coflowai/models/gateway.py"
click node_model_registry "https://github.com/aravindanm20/coflowai/blob/main/coflowai/models/registry.py"
click node_providers "https://github.com/aravindanm20/coflowai/tree/main/coflowai/providers"
click node_context_builder "https://github.com/aravindanm20/coflowai/blob/main/coflowai/context/builder.py"
click node_memory "https://github.com/aravindanm20/coflowai/blob/main/coflowai/memory/base.py"
click node_events "https://github.com/aravindanm20/coflowai/blob/main/coflowai/events/event.py"
click node_state "https://github.com/aravindanm20/coflowai/blob/main/coflowai/state/store.py"
click node_persistence "https://github.com/aravindanm20/coflowai/blob/main/coflowai/persistence/sqlite.py"
click node_replay "https://github.com/aravindanm20/coflowai/blob/main/coflowai/runtime/replay.py"
click node_observability "https://github.com/aravindanm20/coflowai/blob/main/coflowai/observability/logger.py"
click node_distributed "https://github.com/aravindanm20/coflowai/blob/main/coflowai/distributed/worker.py"
click node_plugins "https://github.com/aravindanm20/coflowai/blob/main/coflowai/plugins/loader.py"
click node_result "https://github.com/aravindanm20/coflowai/blob/main/coflowai/core/result.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_app,node_agent,node_workflow,node_result toneBlue
class node_compiler,node_runtime,node_policy,node_context,node_approval,node_tool_exec,node_tool_registry toneAmber
class node_model_gateway,node_model_registry,node_providers,node_context_builder,node_memory toneMint
class node_events,node_state,node_persistence,node_replay toneRose
class node_observability,node_distributed,node_plugins,node_developer toneIndigo
```

## Components

### Developer API

- [Application API](https://github.com/aravindanm20/coflowai/blob/main/coflowai/app.py): `coflowai/app.py`
- [Agent](https://github.com/aravindanm20/coflowai/blob/main/coflowai/agents/agent.py): `coflowai/agents/agent.py`
- [Workflow](https://github.com/aravindanm20/coflowai/blob/main/coflowai/workflows/workflow.py): `coflowai/workflows/workflow.py`
- [Execution Result](https://github.com/aravindanm20/coflowai/blob/main/coflowai/core/result.py): `coflowai/core/result.py`

### Execution Control

- [Workflow Compiler](https://github.com/aravindanm20/coflowai/blob/main/coflowai/workflows/compiler.py): `coflowai/workflows/compiler.py`
- [Execution Runtime](https://github.com/aravindanm20/coflowai/blob/main/coflowai/runtime/runtime.py): `coflowai/runtime/runtime.py`
- [Policy and Budgets](https://github.com/aravindanm20/coflowai/blob/main/coflowai/policies/policy.py): `coflowai/policies/policy.py`
- [Execution Context](https://github.com/aravindanm20/coflowai/blob/main/coflowai/core/context.py): `coflowai/core/context.py`
- [Human Approval](https://github.com/aravindanm20/coflowai/blob/main/coflowai/approvals/approval.py): `coflowai/approvals/approval.py`
- [Tool Execution](https://github.com/aravindanm20/coflowai/blob/main/coflowai/tools/executor.py): `coflowai/tools/executor.py`
- [Tool Registry](https://github.com/aravindanm20/coflowai/blob/main/coflowai/tools/registry.py): `coflowai/tools/registry.py`

### Agent Reasoning

- [Model Gateway](https://github.com/aravindanm20/coflowai/blob/main/coflowai/models/gateway.py): `coflowai/models/gateway.py`
- [Model Registry](https://github.com/aravindanm20/coflowai/blob/main/coflowai/models/registry.py): `coflowai/models/registry.py`
- [Model Providers](https://github.com/aravindanm20/coflowai/tree/main/coflowai/providers): `coflowai/providers`
- [Context Builder](https://github.com/aravindanm20/coflowai/blob/main/coflowai/context/builder.py): `coflowai/context/builder.py`
- [Memory](https://github.com/aravindanm20/coflowai/blob/main/coflowai/memory/base.py): `coflowai/memory/base.py`

### Events and Durability

- [Event Engine](https://github.com/aravindanm20/coflowai/blob/main/coflowai/events/event.py): `coflowai/events/event.py`
- [State and Checkpoints](https://github.com/aravindanm20/coflowai/blob/main/coflowai/state/store.py): `coflowai/state/store.py`
- [Persistence Adapters](https://github.com/aravindanm20/coflowai/blob/main/coflowai/persistence/sqlite.py): `coflowai/persistence/sqlite.py`
- [Replay and Fork](https://github.com/aravindanm20/coflowai/blob/main/coflowai/runtime/replay.py): `coflowai/runtime/replay.py`

### Operations

- [Observability](https://github.com/aravindanm20/coflowai/blob/main/coflowai/observability/logger.py): `coflowai/observability/logger.py`
- [Distributed Workers](https://github.com/aravindanm20/coflowai/blob/main/coflowai/distributed/worker.py): `coflowai/distributed/worker.py`
- [Plugin Loading](https://github.com/aravindanm20/coflowai/blob/main/coflowai/plugins/loader.py): `coflowai/plugins/loader.py`

### Other components

- **Developer / Caller**

## Connections

- Developer / Caller → Application API: submits execution
- Application API → Execution Runtime: runs executable (evidence: `coflowai/app.py`)
- Application API → Model Registry: configures models (evidence: `coflowai/app.py`)
- Application API → Tool Registry: configures tools (evidence: `coflowai/app.py`)
- Application API → State and Checkpoints: configures state (evidence: `coflowai/app.py`)
- Application API → Event Engine: configures events (evidence: `coflowai/app.py`)
- Workflow → Workflow Compiler: compiles graph (evidence: `coflowai/workflows/workflow.py`)
- Execution Runtime → Policy and Budgets: enforces limits (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → Execution Context: creates context (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → State and Checkpoints: saves checkpoints (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → Event Engine: records execution (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → Human Approval: handles decisions (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → Execution Result: returns result (evidence: `coflowai/runtime/runtime.py`)
- Execution Runtime → Observability: emits telemetry (evidence: `coflowai/runtime/runtime.py`)
- Workflow → Human Approval: adds approval gate (evidence: `coflowai/workflows/workflow.py`)
- Agent → Context Builder: builds prompt context (evidence: `coflowai/agents/agent.py`)
- Agent → Model Gateway: requests model
- Agent → Tool Execution: dispatches tool calls
- Agent → Memory: uses memory (evidence: `coflowai/agents/agent.py`)
- Tool Execution → Tool Registry: resolves tools (evidence: `coflowai/tools/executor.py`)
- Model Gateway → Model Registry: resolves provider (evidence: `coflowai/models/gateway.py`)
- Model Gateway → Model Providers: calls adapter
- Execution Context → Policy and Budgets: checks budgets (evidence: `coflowai/core/context.py`)
- Execution Context → Event Engine: emits events (evidence: `coflowai/core/context.py`)
- State and Checkpoints → Persistence Adapters: persisted by adapters (evidence: `coflowai/persistence/sqlite.py`)
- Replay and Fork → State and Checkpoints: loads checkpoints
- Distributed Workers → Execution Runtime: executes jobs (evidence: `coflowai/distributed/worker.py`)
- Distributed Workers → State and Checkpoints: uses checkpoints (evidence: `coflowai/distributed/worker.py`)
- Application API → Plugin Loading: loads plugins (evidence: `coflowai/app.py`)
- Application API → Execution Result: returns execution (evidence: `coflowai/app.py`)
