# furkaanasik/clauflow architecture

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

- Interactive diagram: https://gitdiagram.com/furkaanasik/clauflow
- Repository: https://github.com/furkaanasik/clauflow

## Overview

ClauFlow is an agentic kanban product: users manage project tasks on a board, move work into execution, review the resulting pull request, and merge it. The UI calls the Express API and receives live updates over WebSocket. Backend task transitions dispatch agent runners that use Claude Code and Git/GitHub tooling; review comments trigger work on the existing branch. Project setup, agent topology, skills, GitHub integration, CI, and insights support this workflow. Some subsystem wiring is documented in the README but its implementation was not sampled, so uncertain links are omitted.

Main entry points: [`core/src/services/claudeService.ts`](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/claudeService.ts) (Claude service), [`core/src/index.ts`](https://github.com/furkaanasik/clauflow/blob/master/core/src/index.ts) (HTTP and WS server), [`core/src/routes/tasks.ts`](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/tasks.ts) (Task routes), [`core/src/agents/executor.ts`](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/executor.ts) (Task executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Board UI"]
  node_board["Kanban board<br/>[Board.tsx]"]
  node_board_hooks["Board hooks<br/>[useBoard.ts]"]
  node_socket_hook["Live updates<br/>[useAgentSocket.ts]"]
  node_ui_store["Board state<br/>[boardStore.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Core API"]
  node_server["HTTP and WS server<br/>[index.ts]"]
  node_task_routes["Task routes<br/>[tasks.ts]"]
  node_project_routes["Project routes<br/>[projects.ts]"]
  node_github_routes["GitHub routes<br/>[github.ts]"]
  node_comment_routes["Comment routes<br/>[comments.ts]"]
  node_insight_routes["Insights routes<br/>[insights.ts]"]
end

subgraph group_execution["Task lifecycle"]
  node_executor["Task executor<br/>[executor.ts]"]
  node_comment_runner["Comment runner<br/>[commentRunner.ts]"]
  node_review_runner["PR review runner<br/>[prReviewRunner.ts]"]
  node_planner["Project planner<br/>[projectPlanner.ts]"]
  node_breakdown["Task breakdown"]
  node_git_service["Git and PR service<br/>[gitService.ts]"]
  node_claude_service["Claude service<br/>[claudeService.ts]"]
end

subgraph group_project["Project tools"]
  node_project_tools["Claude project tools<br/>[projectsClaude.ts]"]
  node_graph_routes["Agent graph routes<br/>[graphs.ts]"]
  node_plugin_cli["Skills CLI<br/>[claudePluginCli.ts]"]
  node_github_project_routes["Project GitHub<br/>[projectsGithub.ts]"]
  node_ci_service["CI service<br/>[ciService.ts]"]
end

subgraph group_state["State and integrations"]
  node_ws_service["WebSocket service<br/>[wsService.ts]"]
  node_task_store[("Task and project store<br/>[taskService.ts]")]
  node_comment_service["Comment store<br/>[commentService.ts]"]
end

node_user(("Engineer"))
node_claude_cli{{"Claude Code CLI"}}
node_git_cli{{"Git CLI"}}
node_gh_cli{{"GitHub CLI"}}
node_github{{"GitHub"}}

node_user -->|"manages tasks"| node_board
node_board -->|"moves cards"| node_board_hooks
node_board_hooks -->|"updates tasks"| node_api_client
node_board_hooks -->|"updates state"| node_ui_store
node_api_client -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_task_routes
node_server -->|"dispatches"| node_project_routes
node_server -->|"dispatches"| node_github_routes
node_server -->|"dispatches"| node_comment_routes
node_server -->|"dispatches"| node_insight_routes
node_task_routes -->|"reads and writes"| node_task_store
node_task_routes -->|"queues on DOING"| node_executor
node_executor -->|"manages branch"| node_git_service
node_executor -->|"runs agent"| node_claude_service
node_claude_service -->|"spawns"| node_claude_cli
node_git_service -->|"runs git"| node_git_cli
node_git_service -->|"creates and merges PRs"| node_gh_cli
node_gh_cli -->|"operates on"| node_github
node_comment_routes -->|"stores comments"| node_comment_service
node_comment_routes -->|"dispatches feedback"| node_comment_runner
node_comment_runner -->|"checks out branch"| node_git_service
node_comment_runner -->|"applies feedback"| node_claude_service
node_review_runner -.->|"requests review"| node_claude_service
node_task_routes -.->|"queues PR review"| node_review_runner
node_planner -->|"plans project"| node_claude_service
node_breakdown -->|"breaks down task"| node_claude_service
node_project_tools -->|"manages skills"| node_plugin_cli
node_project_tools -->|"generates agents"| node_claude_service
node_graph_routes -->|"stores graphs"| node_task_store
node_github_project_routes -->|"lists and clones repos"| node_gh_cli
node_ci_service -.->|"runs CI fixes"| node_claude_service
node_task_routes -->|"broadcasts changes"| node_ws_service
node_executor -->|"broadcasts progress"| node_ws_service
node_comment_runner -->|"broadcasts comments"| node_ws_service
node_ws_service -->|"streams events"| node_socket_hook
node_socket_hook -->|"applies updates"| node_ui_store
node_insight_routes -->|"reads task data"| node_task_store

click node_board "https://github.com/furkaanasik/clauflow/blob/master/gui/src/components/Board/Board.tsx"
click node_board_hooks "https://github.com/furkaanasik/clauflow/blob/master/gui/src/hooks/useBoard.ts"
click node_socket_hook "https://github.com/furkaanasik/clauflow/blob/master/gui/src/hooks/useAgentSocket.ts"
click node_ui_store "https://github.com/furkaanasik/clauflow/blob/master/gui/src/store/boardStore.ts"
click node_api_client "https://github.com/furkaanasik/clauflow/blob/master/gui/src/lib/api.ts"
click node_server "https://github.com/furkaanasik/clauflow/blob/master/core/src/index.ts"
click node_task_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/tasks.ts"
click node_project_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projects.ts"
click node_github_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/github.ts"
click node_comment_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/comments.ts"
click node_insight_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/insights.ts"
click node_executor "https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/executor.ts"
click node_comment_runner "https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/commentRunner.ts"
click node_review_runner "https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/prReviewRunner.ts"
click node_planner "https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/projectPlanner.ts"
click node_breakdown "https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/taskBreakdownRunner.ts"
click node_git_service "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/gitService.ts"
click node_claude_service "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/claudeService.ts"
click node_project_tools "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projectsClaude.ts"
click node_graph_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/graphs.ts"
click node_plugin_cli "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/claudePluginCli.ts"
click node_github_project_routes "https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projectsGithub.ts"
click node_ci_service "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/ciService.ts"
click node_ws_service "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/wsService.ts"
click node_task_store "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/taskService.ts"
click node_comment_service "https://github.com/furkaanasik/clauflow/blob/master/core/src/services/commentService.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_board,node_board_hooks,node_socket_hook,node_ui_store,node_api_client toneBlue
class node_server,node_task_routes,node_project_routes,node_github_routes,node_comment_routes,node_insight_routes toneAmber
class node_executor,node_comment_runner,node_review_runner,node_planner,node_breakdown,node_git_service,node_claude_service toneMint
class node_project_tools,node_graph_routes,node_plugin_cli,node_github_project_routes,node_ci_service toneRose
class node_ws_service,node_task_store,node_comment_service,node_user,node_claude_cli,node_git_cli,node_gh_cli,node_github toneIndigo
```

## Components

### Board UI

- [Kanban board](https://github.com/furkaanasik/clauflow/blob/master/gui/src/components/Board/Board.tsx): `gui/src/components/Board/Board.tsx`
- [Board hooks](https://github.com/furkaanasik/clauflow/blob/master/gui/src/hooks/useBoard.ts): `gui/src/hooks/useBoard.ts`
- [Live updates](https://github.com/furkaanasik/clauflow/blob/master/gui/src/hooks/useAgentSocket.ts): `gui/src/hooks/useAgentSocket.ts`
- [Board state](https://github.com/furkaanasik/clauflow/blob/master/gui/src/store/boardStore.ts): `gui/src/store/boardStore.ts`
- [API client](https://github.com/furkaanasik/clauflow/blob/master/gui/src/lib/api.ts): `gui/src/lib/api.ts`

### Core API

- [HTTP and WS server](https://github.com/furkaanasik/clauflow/blob/master/core/src/index.ts): `core/src/index.ts`
- [Task routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/tasks.ts): `core/src/routes/tasks.ts`
- [Project routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projects.ts): `core/src/routes/projects.ts`
- [GitHub routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/github.ts): `core/src/routes/github.ts`
- [Comment routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/comments.ts): `core/src/routes/comments.ts`
- [Insights routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/insights.ts): `core/src/routes/insights.ts`

### Task lifecycle

- [Task executor](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/executor.ts): `core/src/agents/executor.ts`
- [Comment runner](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/commentRunner.ts): `core/src/agents/commentRunner.ts`
- [PR review runner](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/prReviewRunner.ts): `core/src/agents/prReviewRunner.ts`
- [Project planner](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/projectPlanner.ts): `core/src/agents/projectPlanner.ts`
- [Task breakdown](https://github.com/furkaanasik/clauflow/blob/master/core/src/agents/taskBreakdownRunner.ts): `core/src/agents/taskBreakdownRunner.ts`
- [Git and PR service](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/gitService.ts): `core/src/services/gitService.ts`
- [Claude service](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/claudeService.ts): `core/src/services/claudeService.ts`

### Project tools

- [Claude project tools](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projectsClaude.ts): `core/src/routes/projectsClaude.ts`
- [Agent graph routes](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/graphs.ts): `core/src/routes/graphs.ts`
- [Skills CLI](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/claudePluginCli.ts): `core/src/services/claudePluginCli.ts`
- [Project GitHub](https://github.com/furkaanasik/clauflow/blob/master/core/src/routes/projectsGithub.ts): `core/src/routes/projectsGithub.ts`
- [CI service](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/ciService.ts): `core/src/services/ciService.ts`

### State and integrations

- [WebSocket service](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/wsService.ts): `core/src/services/wsService.ts`
- [Task and project store](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/taskService.ts): `core/src/services/taskService.ts`
- [Comment store](https://github.com/furkaanasik/clauflow/blob/master/core/src/services/commentService.ts): `core/src/services/commentService.ts`

### Other components

- **Engineer**
- **Claude Code CLI**
- **Git CLI**
- **GitHub CLI**
- **GitHub**

## Connections

- Engineer → Kanban board: manages tasks
- Kanban board → Board hooks: moves cards
- Board hooks → API client: updates tasks
- Board hooks → Board state: updates state
- API client → HTTP and WS server: HTTP requests
- HTTP and WS server → Task routes: dispatches
- HTTP and WS server → Project routes: dispatches
- HTTP and WS server → GitHub routes: dispatches
- HTTP and WS server → Comment routes: dispatches
- HTTP and WS server → Insights routes: dispatches
- Task routes → Task and project store: reads and writes
- Task routes → Task executor: queues on DOING
- Task executor → Git and PR service: manages branch
- Task executor → Claude service: runs agent
- Claude service → Claude Code CLI: spawns
- Git and PR service → Git CLI: runs git
- Git and PR service → GitHub CLI: creates and merges PRs
- GitHub CLI → GitHub: operates on
- Comment routes → Comment store: stores comments
- Comment routes → Comment runner: dispatches feedback
- Comment runner → Git and PR service: checks out branch
- Comment runner → Claude service: applies feedback
- PR review runner → Claude service: requests review
- Task routes → PR review runner: queues PR review
- Project planner → Claude service: plans project
- Task breakdown → Claude service: breaks down task
- Claude project tools → Skills CLI: manages skills
- Claude project tools → Claude service: generates agents
- Agent graph routes → Task and project store: stores graphs
- Project GitHub → GitHub CLI: lists and clones repos
- CI service → Claude service: runs CI fixes
- Task routes → WebSocket service: broadcasts changes
- Task executor → WebSocket service: broadcasts progress
- Comment runner → WebSocket service: broadcasts comments
- WebSocket service → Live updates: streams events
- Live updates → Board state: applies updates
- Insights routes → Task and project store: reads task data