# frappe/flow_client architecture

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

## Overview

Flow embeds a configurable AI assistant in Frappe, with a Python agent framework behind the Desk chat. A user sends a prompt through the chat panel; a persisted session runs the configured agent, which can call tools, use knowledge retrieval and memory, and records each turn as a Flow Run. Knowledge ingestion and scheduled or DocType-triggered agents are major product capabilities documented by the repository, though their complete wiring is not shown in the excerpts. Edges below are limited to documented or indexed references; dashed links mark unverified integration points.

Main entry points: [`flow/flow/doctype/flow_session/flow_session.py`](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_session/flow_session.py) (Session runtime), [`flow/lib/agent.py`](https://github.com/frappe/flow_client/blob/develop/flow/lib/agent.py) (Agent execution), [`flow/knowledge/retriever.py`](https://github.com/frappe/flow_client/blob/develop/flow/knowledge/retriever.py) (Knowledge retrieval), [`flow/lib/session.py`](https://github.com/frappe/flow_client/blob/develop/flow/lib/session.py) (Session creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Desk chat"]
  node_panel["Chat panel<br/>[App.vue]"]
  node_frontend_store["Chat state<br/>[store.js]"]
  node_api["Chat API<br/>[api.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_session["Session runtime<br/>[flow_session.py]"]
  node_session_factory["Session creation<br/>[session.py]"]
  node_agent["Agent execution<br/>[agent.py]"]
  node_model["Model client<br/>[model.py]"]
  node_run[("Run history<br/>[flow_run.py]")]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_knowledge_ingest["Knowledge ingestion<br/>[ingest.py]"]
  node_knowledge_extract["Content extraction<br/>[extract.py]"]
  node_knowledge_search["Knowledge retrieval<br/>[retriever.py]"]
  node_knowledge_store[("Knowledge index<br/>[store.py]")]
  node_attachment["Chat attachments"]
end

subgraph group_tools["Tools and memory"]
  node_tools["Built-in tools<br/>[builtins.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_memory_store[("Memory search index<br/>[store.py]")]
end

subgraph group_automation["Configuration and automation"]
  node_agent_config["Agent configuration<br/>[flow_agent.py]"]
  node_provider_model["Provider and model settings<br/>[flow_model.py]"]
  node_trigger["Agent triggers<br/>[triggers.py]"]
end

node_user(("Frappe user"))

node_user -->|"opens chat"| node_panel
node_panel -->|"loads state"| node_frontend_store
node_frontend_store -.->|"calls API"| node_api
node_api -->|"creates or loads"| node_session_factory
node_session_factory -->|"assembles agent"| node_agent_config
node_session_factory -->|"creates session"| node_session
node_session -->|"runs runtime"| node_agent
node_agent -->|"requests completions"| node_model
node_agent -->|"invokes tools"| node_tools
node_agent -->|"retrieves knowledge"| node_knowledge_search
node_session -->|"persists run"| node_run
node_session -->|"indexes attachments"| node_attachment
node_session -->|"retrieves attachment chunks"| node_knowledge_search
node_session -->|"builds memory context"| node_memory
node_knowledge_ingest -->|"extracts content"| node_knowledge_extract
node_knowledge_ingest -->|"writes index"| node_knowledge_store
node_knowledge_search -->|"searches index"| node_knowledge_store
node_knowledge_search -.->|"embeds query"| node_knowledge_ingest
node_memory -->|"searches memories"| node_memory_store
node_agent_config -.->|"selects model"| node_provider_model
node_trigger -.->|"starts agent"| node_agent

click node_panel "https://github.com/frappe/flow_client/blob/develop/frontend/src/App.vue"
click node_frontend_store "https://github.com/frappe/flow_client/blob/develop/frontend/src/store.js"
click node_api "https://github.com/frappe/flow_client/blob/develop/flow/api/api.py"
click node_session "https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_session/flow_session.py"
click node_session_factory "https://github.com/frappe/flow_client/blob/develop/flow/lib/session.py"
click node_agent "https://github.com/frappe/flow_client/blob/develop/flow/lib/agent.py"
click node_model "https://github.com/frappe/flow_client/blob/develop/flow/lib/model.py"
click node_run "https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_run/flow_run.py"
click node_agent_config "https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_agent/flow_agent.py"
click node_provider_model "https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_model/flow_model.py"
click node_trigger "https://github.com/frappe/flow_client/blob/develop/flow/triggers/triggers.py"
click node_knowledge_ingest "https://github.com/frappe/flow_client/blob/develop/flow/knowledge/ingest.py"
click node_knowledge_extract "https://github.com/frappe/flow_client/blob/develop/flow/knowledge/extract.py"
click node_knowledge_search "https://github.com/frappe/flow_client/blob/develop/flow/knowledge/retriever.py"
click node_knowledge_store "https://github.com/frappe/flow_client/blob/develop/flow/knowledge/store.py"
click node_attachment "https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_session_attachment/flow_session_attachment.py"
click node_tools "https://github.com/frappe/flow_client/blob/develop/flow/tools/builtins.py"
click node_memory "https://github.com/frappe/flow_client/blob/develop/flow/memory/memory.py"
click node_memory_store "https://github.com/frappe/flow_client/blob/develop/flow/memory/store.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_panel,node_frontend_store,node_api,node_user toneBlue
class node_session,node_session_factory,node_agent,node_model,node_run toneAmber
class node_knowledge_ingest,node_knowledge_extract,node_knowledge_search,node_knowledge_store,node_attachment toneMint
class node_tools,node_memory,node_memory_store toneRose
class node_agent_config,node_provider_model,node_trigger toneIndigo
```

## Components

### Desk chat

- [Chat panel](https://github.com/frappe/flow_client/blob/develop/frontend/src/App.vue): `frontend/src/App.vue`
- [Chat state](https://github.com/frappe/flow_client/blob/develop/frontend/src/store.js): `frontend/src/store.js`
- [Chat API](https://github.com/frappe/flow_client/blob/develop/flow/api/api.py): `flow/api/api.py`

### Agent runtime

- [Session runtime](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_session/flow_session.py): `flow/flow/doctype/flow_session/flow_session.py`
- [Session creation](https://github.com/frappe/flow_client/blob/develop/flow/lib/session.py): `flow/lib/session.py`
- [Agent execution](https://github.com/frappe/flow_client/blob/develop/flow/lib/agent.py): `flow/lib/agent.py`
- [Model client](https://github.com/frappe/flow_client/blob/develop/flow/lib/model.py): `flow/lib/model.py`
- [Run history](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_run/flow_run.py): `flow/flow/doctype/flow_run/flow_run.py`

### Knowledge retrieval

- [Knowledge ingestion](https://github.com/frappe/flow_client/blob/develop/flow/knowledge/ingest.py): `flow/knowledge/ingest.py`
- [Content extraction](https://github.com/frappe/flow_client/blob/develop/flow/knowledge/extract.py): `flow/knowledge/extract.py`
- [Knowledge retrieval](https://github.com/frappe/flow_client/blob/develop/flow/knowledge/retriever.py): `flow/knowledge/retriever.py`
- [Knowledge index](https://github.com/frappe/flow_client/blob/develop/flow/knowledge/store.py): `flow/knowledge/store.py`
- [Chat attachments](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_session_attachment/flow_session_attachment.py): `flow/flow/doctype/flow_session_attachment/flow_session_attachment.py`

### Tools and memory

- [Built-in tools](https://github.com/frappe/flow_client/blob/develop/flow/tools/builtins.py): `flow/tools/builtins.py`
- [Agent memory](https://github.com/frappe/flow_client/blob/develop/flow/memory/memory.py): `flow/memory/memory.py`
- [Memory search index](https://github.com/frappe/flow_client/blob/develop/flow/memory/store.py): `flow/memory/store.py`

### Configuration and automation

- [Agent configuration](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_agent/flow_agent.py): `flow/flow/doctype/flow_agent/flow_agent.py`
- [Provider and model settings](https://github.com/frappe/flow_client/blob/develop/flow/flow/doctype/flow_model/flow_model.py): `flow/flow/doctype/flow_model/flow_model.py`
- [Agent triggers](https://github.com/frappe/flow_client/blob/develop/flow/triggers/triggers.py): `flow/triggers/triggers.py`

### Other components

- **Frappe user**

## Connections

- Frappe user → Chat panel: opens chat
- Chat panel → Chat state: loads state (evidence: `frontend/src/App.vue`)
- Chat state → Chat API: calls API
- Chat API → Session creation: creates or loads (evidence: `flow/api/api.py`)
- Session creation → Agent configuration: assembles agent (evidence: `flow/lib/session.py`)
- Session creation → Session runtime: creates session (evidence: `flow/lib/session.py`)
- Session runtime → Agent execution: runs runtime (evidence: `flow/flow/doctype/flow_session/flow_session.py`)
- Agent execution → Model client: requests completions (evidence: `flow/lib/agent.py`)
- Agent execution → Built-in tools: invokes tools (evidence: `flow/lib/agent.py`)
- Agent execution → Knowledge retrieval: retrieves knowledge (evidence: `flow/lib/agent.py`)
- Session runtime → Run history: persists run (evidence: `flow/flow/doctype/flow_session/flow_session.py`)
- Session runtime → Chat attachments: indexes attachments (evidence: `flow/flow/doctype/flow_session/flow_session.py`)
- Session runtime → Knowledge retrieval: retrieves attachment chunks (evidence: `flow/flow/doctype/flow_session/flow_session.py`)
- Session runtime → Agent memory: builds memory context (evidence: `flow/flow/doctype/flow_session/flow_session.py`)
- Knowledge ingestion → Content extraction: extracts content (evidence: `flow/knowledge/ingest.py`)
- Knowledge ingestion → Knowledge index: writes index (evidence: `flow/knowledge/ingest.py`)
- Knowledge retrieval → Knowledge index: searches index (evidence: `flow/knowledge/retriever.py`)
- Knowledge retrieval → Knowledge ingestion: embeds query
- Agent memory → Memory search index: searches memories (evidence: `flow/memory/memory.py`)
- Agent configuration → Provider and model settings: selects model
- Agent triggers → Agent execution: starts agent
