# flow-research/garden architecture

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

- Interactive diagram: https://gitdiagram.com/flow-research/garden
- Repository: https://github.com/flow-research/garden

## Overview

Garden is a shared workspace where people and persistent AI agents coordinate chats, tasks, automations, skills, connected tools, documents, and approvals. The main user workflow is to enter the tabbed workspace, start or resume an agent chat, provide context such as files, and follow the agent’s work and approval requests. The graph covers that interaction plus the documented task, automation, knowledge, and integration capabilities. Several feature implementations were not sampled; those branches are represented at their exact feature-directory paths, with README evidence where appropriate.

Main entry points: [`apps/web/src/features/chat/components/chat-panel-controller.tsx`](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-panel-controller.tsx) (Chat panel), [`packages/agent-runtime/src/runtime-mcp-controller.ts`](https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/runtime-mcp-controller.ts) (Tool controller), [`apps/web/src/features/chat/chat-runtime-provider.tsx`](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/chat-runtime-provider.tsx) (Chat runtime), [`packages/brain/src/services/Brain.ts`](https://github.com/flow-research/garden/blob/main/packages/brain/src/services/Brain.ts) (Workspace knowledge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["Garden workspace<br/>[app-shell.tsx]"]
end

subgraph group_agent["Agent interaction"]
  node_chat["Chat panel"]
  node_composer["Chat composer<br/>[chat-composer.tsx]"]
  node_chatruntime["Chat runtime"]
  node_agentserver["Agent request router<br/>[server.ts]"]
  node_skills["Agent skills"]
end

subgraph group_work["Team work"]
  node_tasks["Tasks and issues"]
  node_issue_service["Issue run service<br/>[run-service.ts]"]
  node_automations["Automations"]
  node_automation_service["Automation runs<br/>[run-service.ts]"]
  node_db[("Application database<br/>[client.ts]")]
end

subgraph group_knowledge["Knowledge and documents"]
  node_brain["Workspace knowledge<br/>[Brain.ts]"]
  node_brain_worker["Brain worker composition<br/>[worker.ts]"]
  node_helix[("Helix graph store<br/>[HelixClient.ts]")]
  node_file_ingestion["File ingestion"]
  node_documents["Chat documents"]
  node_artifact_engine["Document artifact engine"]
  node_artifact_repository[("Artifact repository")]
end

subgraph group_integrations["Tools and governance"]
  node_mcp["Tool controller"]
  node_approvals["Permissions and approvals<br/>[permissions.ts]"]
  node_connectors["Connected tools<br/>[github-app.ts]"]
end

node_person(("Team member"))
node_github{{"GitHub"}}

node_person -->|"uses"| node_app
node_app -->|"opens chat"| node_chat
node_chat -->|"binds runtime"| node_chatruntime
node_chat -->|"renders"| node_composer
node_composer -->|"sends turns"| node_chatruntime
node_chatruntime -.->|"connects agent"| node_agentserver
node_agentserver -->|"routes agent requests"| node_mcp
node_mcp -->|"checks trust"| node_approvals
node_mcp -->|"resolves tools"| node_connectors
node_connectors -.->|"integrates"| node_github
node_person -->|"tracks work"| node_tasks
node_tasks -->|"starts issue run"| node_issue_service
node_issue_service -->|"persists issues"| node_db
node_person -->|"configures runs"| node_automations
node_automations -.->|"schedules work"| node_automation_service
node_person -->|"manages skills"| node_skills
node_person -->|"uses workspace knowledge"| node_brain
node_file_ingestion -->|"ingests files"| node_brain
node_brain_worker -->|"composes services"| node_brain
node_brain_worker -->|"configures client"| node_helix
node_person -->|"attaches documents"| node_documents
node_documents -.->|"edits artifacts"| node_artifact_engine
node_artifact_engine -->|"transacts snapshots"| node_artifact_repository

click node_app "https://github.com/flow-research/garden/blob/main/apps/web/src/components/shell/app-shell.tsx"
click node_chat "https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-panel-controller.tsx"
click node_composer "https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-composer.tsx"
click node_chatruntime "https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/chat-runtime-provider.tsx"
click node_agentserver "https://github.com/flow-research/garden/blob/main/apps/web/src/server.ts"
click node_mcp "https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/runtime-mcp-controller.ts"
click node_approvals "https://github.com/flow-research/garden/blob/main/packages/core/src/agents/permissions.ts"
click node_connectors "https://github.com/flow-research/garden/blob/main/packages/connectors/src/github-app.ts"
click node_tasks "https://github.com/flow-research/garden/tree/main/apps/web/src/features/issues"
click node_issue_service "https://github.com/flow-research/garden/blob/main/packages/server/src/issues/run-service.ts"
click node_automations "https://github.com/flow-research/garden/tree/main/apps/web/src/features/automations"
click node_automation_service "https://github.com/flow-research/garden/blob/main/packages/server/src/automations/run-service.ts"
click node_skills "https://github.com/flow-research/garden/tree/main/apps/web/src/features/skills"
click node_brain "https://github.com/flow-research/garden/blob/main/packages/brain/src/services/Brain.ts"
click node_brain_worker "https://github.com/flow-research/garden/blob/main/packages/brain/src/services/worker.ts"
click node_helix "https://github.com/flow-research/garden/blob/main/packages/brain/src/services/HelixClient.ts"
click node_file_ingestion "https://github.com/flow-research/garden/blob/main/apps/web/src/lib/server/brain-file-ingestion.ts"
click node_documents "https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-document-panel.tsx"
click node_artifact_engine "https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/documents/document-artifact-engine.ts"
click node_artifact_repository "https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/documents/document-artifact-repository.ts"
click node_db "https://github.com/flow-research/garden/blob/main/packages/db/src/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_app toneBlue
class node_chat,node_composer,node_chatruntime,node_agentserver,node_skills toneAmber
class node_tasks,node_issue_service,node_automations,node_automation_service,node_db toneMint
class node_brain,node_brain_worker,node_helix,node_file_ingestion,node_documents,node_artifact_engine,node_artifact_repository toneRose
class node_mcp,node_approvals,node_connectors,node_person,node_github toneIndigo
```

## Components

### Workspace UI

- [Garden workspace](https://github.com/flow-research/garden/blob/main/apps/web/src/components/shell/app-shell.tsx): `apps/web/src/components/shell/app-shell.tsx`

### Agent interaction

- [Chat panel](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-panel-controller.tsx): `apps/web/src/features/chat/components/chat-panel-controller.tsx`
- [Chat composer](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-composer.tsx): `apps/web/src/features/chat/components/chat-composer.tsx`
- [Chat runtime](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/chat-runtime-provider.tsx): `apps/web/src/features/chat/chat-runtime-provider.tsx`
- [Agent request router](https://github.com/flow-research/garden/blob/main/apps/web/src/server.ts): `apps/web/src/server.ts`
- [Agent skills](https://github.com/flow-research/garden/tree/main/apps/web/src/features/skills): `apps/web/src/features/skills`

### Team work

- [Tasks and issues](https://github.com/flow-research/garden/tree/main/apps/web/src/features/issues): `apps/web/src/features/issues`
- [Issue run service](https://github.com/flow-research/garden/blob/main/packages/server/src/issues/run-service.ts): `packages/server/src/issues/run-service.ts`
- [Automations](https://github.com/flow-research/garden/tree/main/apps/web/src/features/automations): `apps/web/src/features/automations`
- [Automation runs](https://github.com/flow-research/garden/blob/main/packages/server/src/automations/run-service.ts): `packages/server/src/automations/run-service.ts`
- [Application database](https://github.com/flow-research/garden/blob/main/packages/db/src/client.ts): `packages/db/src/client.ts`

### Knowledge and documents

- [Workspace knowledge](https://github.com/flow-research/garden/blob/main/packages/brain/src/services/Brain.ts): `packages/brain/src/services/Brain.ts`
- [Brain worker composition](https://github.com/flow-research/garden/blob/main/packages/brain/src/services/worker.ts): `packages/brain/src/services/worker.ts`
- [Helix graph store](https://github.com/flow-research/garden/blob/main/packages/brain/src/services/HelixClient.ts): `packages/brain/src/services/HelixClient.ts`
- [File ingestion](https://github.com/flow-research/garden/blob/main/apps/web/src/lib/server/brain-file-ingestion.ts): `apps/web/src/lib/server/brain-file-ingestion.ts`
- [Chat documents](https://github.com/flow-research/garden/blob/main/apps/web/src/features/chat/components/chat-document-panel.tsx): `apps/web/src/features/chat/components/chat-document-panel.tsx`
- [Document artifact engine](https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/documents/document-artifact-engine.ts): `packages/agent-runtime/src/documents/document-artifact-engine.ts`
- [Artifact repository](https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/documents/document-artifact-repository.ts): `packages/agent-runtime/src/documents/document-artifact-repository.ts`

### Tools and governance

- [Tool controller](https://github.com/flow-research/garden/blob/main/packages/agent-runtime/src/runtime-mcp-controller.ts): `packages/agent-runtime/src/runtime-mcp-controller.ts`
- [Permissions and approvals](https://github.com/flow-research/garden/blob/main/packages/core/src/agents/permissions.ts): `packages/core/src/agents/permissions.ts`
- [Connected tools](https://github.com/flow-research/garden/blob/main/packages/connectors/src/github-app.ts): `packages/connectors/src/github-app.ts`

### Other components

- **Team member**
- **GitHub**

## Connections

- Team member → Garden workspace: uses (evidence: `README.md`)
- Garden workspace → Chat panel: opens chat (evidence: `README.md`)
- Chat panel → Chat runtime: binds runtime (evidence: `apps/web/src/features/chat/components/chat-panel-controller.tsx`)
- Chat panel → Chat composer: renders (evidence: `apps/web/src/features/chat/components/chat-panel-controller.tsx`)
- Chat composer → Chat runtime: sends turns (evidence: `apps/web/src/features/chat/components/chat-composer.tsx`)
- Chat runtime → Agent request router: connects agent
- Agent request router → Tool controller: routes agent requests (evidence: `apps/web/src/server.ts`)
- Tool controller → Permissions and approvals: checks trust (evidence: `packages/agent-runtime/src/runtime-mcp-controller.ts`)
- Tool controller → Connected tools: resolves tools (evidence: `packages/agent-runtime/src/runtime-mcp-controller.ts`)
- Connected tools → GitHub: integrates (evidence: `README.md`)
- Team member → Tasks and issues: tracks work (evidence: `README.md`)
- Tasks and issues → Issue run service: starts issue run
- Issue run service → Application database: persists issues (evidence: `packages/server/src/issues/run-service.ts`)
- Team member → Automations: configures runs (evidence: `README.md`)
- Automations → Automation runs: schedules work (evidence: `README.md`)
- Team member → Agent skills: manages skills (evidence: `README.md`)
- Team member → Workspace knowledge: uses workspace knowledge (evidence: `README.md`)
- File ingestion → Workspace knowledge: ingests files (evidence: `apps/web/src/lib/server/brain-file-ingestion.ts`)
- Brain worker composition → Workspace knowledge: composes services (evidence: `packages/brain/src/services/worker.ts`)
- Brain worker composition → Helix graph store: configures client (evidence: `packages/brain/src/services/worker.ts`)
- Team member → Chat documents: attaches documents (evidence: `README.md`)
- Chat documents → Document artifact engine: edits artifacts
- Document artifact engine → Artifact repository: transacts snapshots (evidence: `packages/agent-runtime/src/documents/document-artifact-engine.ts`)
