# netanelrotem/agent-demo-taskboard architecture

> Architecture diagram of the GitHub repository netanelrotem/agent-demo-taskboard, 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/netanelrotem/agent-demo-taskboard
- Repository: https://github.com/netanelrotem/agent-demo-taskboard

## Overview

The repository combines a small Todo taskboard and a FastAPI GitHub-webhook service that runs an issue-driven coding agent. The agent workflow accepts commands, coordinates planning and human input, executes repository changes, verifies them, and handles review feedback; GitHub API access, workspace management, persistence, and run events support that workflow. The Todo UI manages tasks and presentation state in a single React component. The graph reflects shown excerpts and SOURCE INDEX references; unsampled implementation details and some runtime wiring are not asserted.

Main entry points: [`coding-agent-graph/service.py`](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/service.py) (Run service), [`coding-agent-graph/agent_graph.py`](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/agent_graph.py) (Agent workflow), [`coding-agent-graph/events.py`](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/events.py) (Run events), [`coding-agent-graph/pi_runner.py`](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/pi_runner.py) (Pi runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_taskboard["Todo taskboard"]
  node_todo_ui["Todo interface<br/>[App.tsx]"]
end

subgraph group_ingress["Webhook ingress"]
  node_webhook["Webhook handler<br/>[main.py]"]
  node_service["Run service<br/>[service.py]"]
  node_commands["Command parsing<br/>[commands.py]"]
end

subgraph group_workflow["Agent workflow"]
  node_models["Agent models<br/>[agent_models.py]"]
  node_graph["Agent workflow<br/>[agent_graph.py]"]
end

subgraph group_execution["Execution"]
  node_workspace["Repository workspace<br/>[workspace.py]"]
  node_pi_runner["Pi runner<br/>[pi_runner.py]"]
  node_cloud_sandbox["Cloud sandbox<br/>[cloud_sandbox.py]"]
end

subgraph group_integrations["State and integrations"]
  node_github_client["GitHub client<br/>[github_client.py]"]
  node_storage[("Run storage<br/>[storage.py]")]
  node_events["Run events<br/>[events.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_todo_user(("Taskboard user"))
node_github_user(("GitHub user"))
node_github_api["GitHub API"]
node_telegram["Telegram"]

node_todo_user -->|"manages tasks"| node_todo_ui
node_github_user -->|"sends commands"| node_webhook
node_webhook -->|"queues work"| node_service
node_service -->|"parses commands"| node_commands
node_service -->|"runs workflow"| node_graph
node_service -->|"records runs"| node_storage
node_service -->|"creates runner"| node_pi_runner
node_service -->|"selects cloud mode"| node_cloud_sandbox
node_service -->|"records events"| node_events
node_graph -->|"loads review feedback"| node_github_client
node_graph -->|"loads run state"| node_storage
node_graph -->|"uses workspaces"| node_workspace
node_graph -->|"runs agent"| node_pi_runner
node_github_client -->|"calls API"| node_github_api
node_pi_runner -->|"emits events"| node_events
node_cloud_sandbox -->|"extends workspace"| node_workspace
node_events -->|"stores topics"| node_storage
node_events -.->|"notifies optionally"| node_telegram
node_service -->|"uses settings"| node_settings

click node_todo_ui "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/todo-app/src/App.tsx"
click node_webhook "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/main.py"
click node_service "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/service.py"
click node_commands "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/commands.py"
click node_models "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/agent_models.py"
click node_graph "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/agent_graph.py"
click node_github_client "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/github_client.py"
click node_workspace "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/workspace.py"
click node_pi_runner "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/pi_runner.py"
click node_cloud_sandbox "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/cloud_sandbox.py"
click node_storage "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/storage.py"
click node_events "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/events.py"
click node_settings "https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/config.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_todo_ui,node_github_user toneBlue
class node_webhook,node_service,node_commands toneAmber
class node_models,node_graph,node_github_api toneMint
class node_workspace,node_pi_runner,node_cloud_sandbox,node_todo_user toneRose
class node_github_client,node_storage,node_events,node_settings,node_telegram toneIndigo
```

## Components

### Todo taskboard

- [Todo interface](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/todo-app/src/App.tsx): `todo-app/src/App.tsx`

### Webhook ingress

- [Webhook handler](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/main.py): `coding-agent-graph/main.py`
- [Run service](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/service.py): `coding-agent-graph/service.py`
- [Command parsing](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/commands.py): `coding-agent-graph/commands.py`

### Agent workflow

- [Agent models](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/agent_models.py): `coding-agent-graph/agent_models.py`
- [Agent workflow](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/agent_graph.py): `coding-agent-graph/agent_graph.py`

### Execution

- [Repository workspace](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/workspace.py): `coding-agent-graph/workspace.py`
- [Pi runner](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/pi_runner.py): `coding-agent-graph/pi_runner.py`
- [Cloud sandbox](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/cloud_sandbox.py): `coding-agent-graph/cloud_sandbox.py`

### State and integrations

- [GitHub client](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/github_client.py): `coding-agent-graph/github_client.py`
- [Run storage](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/storage.py): `coding-agent-graph/storage.py`
- [Run events](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/events.py): `coding-agent-graph/events.py`
- [Runtime settings](https://github.com/netanelrotem/agent-demo-taskboard/blob/main/coding-agent-graph/config.py): `coding-agent-graph/config.py`

### Other components

- **Taskboard user**
- **GitHub user**
- **GitHub API**
- **Telegram**

## Connections

- Taskboard user → Todo interface: manages tasks (evidence: `todo-app/src/App.tsx`)
- GitHub user → Webhook handler: sends commands (evidence: `coding-agent-graph/main.py`)
- Webhook handler → Run service: queues work (evidence: `coding-agent-graph/main.py`)
- Run service → Command parsing: parses commands (evidence: `coding-agent-graph/main.py`)
- Run service → Agent workflow: runs workflow (evidence: `coding-agent-graph/service.py`)
- Run service → Run storage: records runs (evidence: `coding-agent-graph/service.py`)
- Run service → Pi runner: creates runner (evidence: `coding-agent-graph/service.py`)
- Run service → Cloud sandbox: selects cloud mode (evidence: `coding-agent-graph/service.py`)
- Run service → Run events: records events (evidence: `coding-agent-graph/service.py`)
- Agent workflow → GitHub client: loads review feedback (evidence: `coding-agent-graph/agent_graph.py`)
- Agent workflow → Run storage: loads run state (evidence: `coding-agent-graph/agent_graph.py`)
- Agent workflow → Repository workspace: uses workspaces (evidence: `coding-agent-graph/agent_graph.py`)
- Agent workflow → Pi runner: runs agent (evidence: `coding-agent-graph/agent_graph.py`)
- GitHub client → GitHub API: calls API (evidence: `coding-agent-graph/github_client.py`)
- Pi runner → Run events: emits events (evidence: `coding-agent-graph/pi_runner.py`)
- Cloud sandbox → Repository workspace: extends workspace (evidence: `coding-agent-graph/cloud_sandbox.py`)
- Run events → Run storage: stores topics (evidence: `coding-agent-graph/events.py`)
- Run events → Telegram: notifies optionally (evidence: `coding-agent-graph/events.py`)
- Run service → Runtime settings: uses settings (evidence: `coding-agent-graph/service.py`)
