# alok-yadav25/devpilot architecture

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

- Interactive diagram: https://gitdiagram.com/alok-yadav25/devpilot
- Repository: https://github.com/alok-yadav25/devpilot

## Overview

DevPilot is a web and CLI agent for investigating reproducible Python/pytest bugs. The main user workflow is to submit a public repository and bug report, reproduce the failure, investigate and propose a bounded patch, test it in a selected sandbox, then pause for exact-diff human review; only approval permits target-branch and draft-PR publication. The graph emphasizes the website-to-API workflow and its durable worker, while retaining replay and evaluation capabilities. Several backend routes and runner implementations are represented from the tree and README; their internal calls are not inferred where excerpts do not establish them.

Main entry points: [`backend/app/agent/graph.py`](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/graph.py) (Repair graph), [`backend/app/service.py`](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/service.py) (Run service), [`backend/app/main.py`](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/main.py) (FastAPI app), [`frontend/src/pages/Workspace.tsx`](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/Workspace.tsx) (Workspace pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Workspace UI"]
  node_workspace["Workspace pages<br/>[Workspace.tsx]"]
  node_newrun["New run form<br/>[NewRun.tsx]"]
  node_liveview["Live run view<br/>[LiveRun.tsx]"]
  node_uiprimitives["UI primitives<br/>[button.tsx]"]
  node_dialog["Connection dialog<br/>[dialog.tsx]"]
  node_client["API client<br/>[client.ts]"]
  node_apiwrapper["Run API<br/>[api.ts]"]
  node_localstate["Workspace state<br/>[store.ts]"]
end

subgraph group_api["API and persistence"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_routes["Run and event routes<br/>[runs.py]"]
  node_service["Run service<br/>[service.py]"]
  node_database[("Run records<br/>[models.py]")]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_repair["Repair workflow"]
  node_agent["Repair graph<br/>[graph.py]"]
  node_agentstate["Graph state<br/>[state.py]"]
  node_retrieval["Source retrieval<br/>[retrieval.py]"]
  node_llm["LLM integration<br/>[llm.py]"]
  node_patches["Patch validation<br/>[patches.py]"]
end

subgraph group_execution["Execution and integrations"]
  node_clone["Repository checkout<br/>[clone.py]"]
  node_policy["Repository policy<br/>[policy.py]"]
  node_runnerfactory["Runner selection<br/>[factory.py]"]
  node_actions["Actions sandbox<br/>[github_actions.py]"]
  node_docker["Docker runner<br/>[docker_runner.py]"]
end

subgraph group_review["Review and records"]
  node_review["Review gate<br/>[service.py]"]
  node_pr["Draft PR publication<br/>[pr.py]"]
  node_replays["Recorded replay API<br/>[replays.py]"]
  node_evaluation["Evaluation API<br/>[eval.py]"]
  node_examples["Walkthrough examples<br/>[examples.ts]"]
end

node_user(("Engineer"))
node_sandboxrepo["GitHub sandbox"]
node_github["Target GitHub"]

node_user -->|"opens"| node_workspace
node_workspace -->|"starts runs"| node_newrun
node_newrun -->|"submits run"| node_apiwrapper
node_apiwrapper -->|"sends requests"| node_client
node_client -->|"calls REST/SSE"| node_backend
node_backend -->|"mounts routes"| node_routes
node_routes -->|"dispatches runs"| node_service
node_service -->|"persists checkpoints"| node_database
node_service -->|"runs workflow"| node_agent
node_agent -->|"updates state"| node_agentstate
node_agent -->|"requests generation"| node_llm
node_agent -->|"locates source"| node_retrieval
node_agent -->|"validates diff"| node_patches
node_agent -->|"checks out repository"| node_clone
node_agent -->|"checks eligibility"| node_policy
node_service -->|"selects runner"| node_runnerfactory
node_runnerfactory -->|"creates runner"| node_actions
node_runnerfactory -->|"creates runner"| node_docker
node_actions -->|"dispatches jobs"| node_sandboxrepo
node_service -->|"awaits approval"| node_review
node_user -->|"approves exact diff"| node_review
node_review -->|"publishes after approval"| node_pr
node_pr -->|"creates draft PR"| node_github
node_service -->|"stores run events"| node_database
node_backend -->|"configures runtime"| node_settings
node_backend -->|"mounts routes"| node_replays
node_backend -->|"mounts routes"| node_evaluation
node_liveview -->|"loads run data"| node_apiwrapper
node_liveview -->|"renders controls"| node_uiprimitives
node_workspace -->|"uses workspace state"| node_localstate
node_localstate -->|"advances walkthrough"| node_examples
node_workspace -->|"connects worker"| node_dialog

click node_workspace "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/Workspace.tsx"
click node_newrun "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/NewRun.tsx"
click node_liveview "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/LiveRun.tsx"
click node_uiprimitives "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/components/ui/button.tsx"
click node_dialog "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/components/ui/dialog.tsx"
click node_client "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/client.ts"
click node_apiwrapper "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/api.ts"
click node_localstate "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/store.ts"
click node_backend "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/main.py"
click node_routes "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/runs.py"
click node_service "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/service.py"
click node_database "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/db/models.py"
click node_settings "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/config.py"
click node_agent "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/graph.py"
click node_agentstate "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/state.py"
click node_retrieval "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/tools/retrieval.py"
click node_llm "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/llm.py"
click node_patches "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/tools/patches.py"
click node_clone "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/github/clone.py"
click node_policy "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/policy.py"
click node_runnerfactory "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/factory.py"
click node_actions "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/github_actions.py"
click node_docker "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/docker_runner.py"
click node_review "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/service.py"
click node_pr "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/github/pr.py"
click node_replays "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/replays.py"
click node_evaluation "https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/eval.py"
click node_examples "https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/examples.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_workspace,node_newrun,node_liveview,node_uiprimitives,node_dialog,node_client,node_apiwrapper,node_localstate toneBlue
class node_backend,node_routes,node_service,node_database,node_settings toneAmber
class node_agent,node_agentstate,node_retrieval,node_llm,node_patches toneMint
class node_clone,node_policy,node_runnerfactory,node_actions,node_docker toneRose
class node_review,node_pr,node_replays,node_evaluation,node_examples,node_user,node_sandboxrepo,node_github toneIndigo
```

## Components

### Workspace UI

- [Workspace pages](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/Workspace.tsx): `frontend/src/pages/Workspace.tsx`
- [New run form](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/NewRun.tsx): `frontend/src/pages/NewRun.tsx`
- [Live run view](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/pages/LiveRun.tsx): `frontend/src/pages/LiveRun.tsx`
- [UI primitives](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/components/ui/button.tsx): `frontend/src/components/ui/button.tsx`
- [Connection dialog](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/components/ui/dialog.tsx): `frontend/src/components/ui/dialog.tsx`
- [API client](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/client.ts): `frontend/src/lib/client.ts`
- [Run API](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Workspace state](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/store.ts): `frontend/src/lib/store.ts`

### API and persistence

- [FastAPI app](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Run and event routes](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/runs.py): `backend/app/api/runs.py`
- [Run service](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/service.py): `backend/app/service.py`
- [Run records](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Runtime settings](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/config.py): `backend/app/config.py`

### Repair workflow

- [Repair graph](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/graph.py): `backend/app/agent/graph.py`
- [Graph state](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/state.py): `backend/app/agent/state.py`
- [Source retrieval](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/tools/retrieval.py): `backend/app/agent/tools/retrieval.py`
- [LLM integration](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/llm.py): `backend/app/agent/llm.py`
- [Patch validation](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/agent/tools/patches.py): `backend/app/agent/tools/patches.py`

### Execution and integrations

- [Repository checkout](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/github/clone.py): `backend/app/github/clone.py`
- [Repository policy](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/policy.py): `backend/app/policy.py`
- [Runner selection](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/factory.py): `backend/app/sandbox/factory.py`
- [Actions sandbox](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/github_actions.py): `backend/app/sandbox/github_actions.py`
- [Docker runner](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/sandbox/docker_runner.py): `backend/app/sandbox/docker_runner.py`

### Review and records

- [Review gate](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/service.py): `backend/app/service.py`
- [Draft PR publication](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/github/pr.py): `backend/app/github/pr.py`
- [Recorded replay API](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/replays.py): `backend/app/api/replays.py`
- [Evaluation API](https://github.com/alok-yadav25/devpilot/blob/main/backend/app/api/eval.py): `backend/app/api/eval.py`
- [Walkthrough examples](https://github.com/alok-yadav25/devpilot/blob/main/frontend/src/lib/examples.ts): `frontend/src/lib/examples.ts`

### Other components

- **Engineer**
- **GitHub sandbox**
- **Target GitHub**

## Connections

- Engineer → Workspace pages: opens (evidence: `README.md`)
- Workspace pages → New run form: starts runs (evidence: `frontend/src/main.tsx`)
- New run form → Run API: submits run (evidence: `frontend/src/pages/NewRun.tsx`)
- Run API → API client: sends requests (evidence: `frontend/src/lib/api.ts`)
- API client → FastAPI app: calls REST/SSE (evidence: `README.md`)
- FastAPI app → Run and event routes: mounts routes (evidence: `backend/app/main.py`)
- Run and event routes → Run service: dispatches runs (evidence: `backend/app/api/runs.py`)
- Run service → Run records: persists checkpoints (evidence: `backend/app/service.py`)
- Run service → Repair graph: runs workflow (evidence: `backend/app/service.py`)
- Repair graph → Graph state: updates state (evidence: `backend/app/agent/graph.py`)
- Repair graph → LLM integration: requests generation (evidence: `backend/app/agent/graph.py`)
- Repair graph → Source retrieval: locates source (evidence: `backend/app/agent/graph.py`)
- Repair graph → Patch validation: validates diff (evidence: `backend/app/agent/graph.py`)
- Repair graph → Repository checkout: checks out repository (evidence: `backend/app/agent/graph.py`)
- Repair graph → Repository policy: checks eligibility (evidence: `backend/app/agent/graph.py`)
- Run service → Runner selection: selects runner (evidence: `backend/app/service.py`)
- Runner selection → Actions sandbox: creates runner (evidence: `backend/app/sandbox/factory.py`)
- Runner selection → Docker runner: creates runner (evidence: `backend/app/sandbox/factory.py`)
- Actions sandbox → GitHub sandbox: dispatches jobs (evidence: `README.md`)
- Run service → Review gate: awaits approval (evidence: `README.md`)
- Engineer → Review gate: approves exact diff (evidence: `README.md`)
- Review gate → Draft PR publication: publishes after approval (evidence: `README.md`)
- Draft PR publication → Target GitHub: creates draft PR (evidence: `README.md`)
- Run service → Run records: stores run events (evidence: `backend/app/service.py`)
- FastAPI app → Runtime settings: configures runtime (evidence: `backend/app/main.py`)
- FastAPI app → Recorded replay API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Evaluation API: mounts routes (evidence: `backend/app/main.py`)
- Live run view → Run API: loads run data (evidence: `frontend/src/pages/LiveRun.tsx`)
- Live run view → UI primitives: renders controls (evidence: `frontend/src/pages/LiveRun.tsx`)
- Workspace pages → Workspace state: uses workspace state
- Workspace state → Walkthrough examples: advances walkthrough (evidence: `frontend/src/lib/store.ts`)
- Workspace pages → Connection dialog: connects worker
