# jeff-jayden/auto_dev_agent architecture

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

- Interactive diagram: https://gitdiagram.com/jeff-jayden/auto_dev_agent
- Repository: https://github.com/jeff-jayden/auto_dev_agent

## Overview

AI Dev Agent turns a user requirement into a reviewed, human-gated GitHub delivery. The principal workflow is repository analysis and retrieval, requirement planning and approval, isolated development with test/repair cycles, independent review, then Draft PR publication and human merge. Jobs and LangGraph support pausing and recovery; SQLite and tracing provide durable state and auditability. README documents broader capabilities than the sampled excerpts, so links for those areas follow its explicit architecture and workflow descriptions; uncertain implementation-level wiring is omitted.

Main entry points: [`src/workflows/orchestrator.py`](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/orchestrator.py) (Task orchestrator), [`src/workflows/workflow_graph.py`](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/workflow_graph.py) (Delivery graph), [`src/infrastructure/store.py`](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/infrastructure/store.py) (SQLite task store), [`apps/api/main.py`](https://github.com/jeff-jayden/auto_dev_agent/blob/main/apps/api/main.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_runtime["API and execution"]
  node_api["FastAPI<br/>[main.py]"]
  node_worker["Job worker<br/>[worker.py]"]
  node_store[("SQLite task store<br/>[store.py]")]
end

subgraph group_workflow["Delivery workflow"]
  node_orchestrator["Task orchestrator<br/>[orchestrator.py]"]
  node_graph["Delivery graph<br/>[workflow_graph.py]"]
  node_recovery["Recovery coordinator<br/>[recovery.py]"]
  node_models["Domain state<br/>[models.py]"]
end

subgraph group_intelligence["Repository intelligence"]
  node_repo_analyzer["Repository analyzer<br/>[analyzer.py]"]
  node_repo_catalog["Repository catalog<br/>[catalog.py]"]
  node_indexer["Code indexer<br/>[indexer.py]"]
  node_retrieval_eval["Retrieval evaluation<br/>[retrieval.py]"]
  node_golden_eval["Golden evaluation<br/>[golden.py]"]
end

subgraph group_agents_tools["Agents and tools"]
  node_planner["Planning agent"]
  node_explorer["Exploration agent"]
  node_developer["Development agent"]
  node_reviewer["Review agent"]
  node_mr_builder["PR description"]
  node_toolkit["Developer toolkit"]
  node_policy["Tool policy<br/>[policy.py]"]
end

subgraph group_delivery_support["Delivery and support"]
  node_workspace["Git worktree<br/>[workspace.py]"]
  node_gateway["Model gateway<br/>[gateway.py]"]
  node_publisher["PR publisher<br/>[publisher.py]"]
  node_ui_validation["UI acceptance<br/>[ui_validation.py]"]
  node_tracing["Tracing<br/>[tracing.py]"]
end

node_user(("User"))
node_github["GitHub"]
node_figma["Figma MCP"]

node_user -->|"submits decisions"| node_api
node_api -->|"requests actions"| node_orchestrator
node_api -->|"queues jobs"| node_worker
node_api -->|"reads projections"| node_store
node_worker -->|"dispatches jobs"| node_orchestrator
node_worker -->|"claims and updates"| node_store
node_worker -->|"requests recovery"| node_recovery
node_orchestrator -->|"runs workflow"| node_graph
node_graph -->|"runs planning"| node_planner
node_graph -->|"requests context"| node_explorer
node_graph -->|"runs development"| node_developer
node_graph -->|"runs review"| node_reviewer
node_orchestrator -->|"analyzes repository"| node_repo_analyzer
node_repo_analyzer -->|"uses repository facts"| node_repo_catalog
node_repo_analyzer -->|"builds retrieval context"| node_indexer
node_planner -->|"calls model"| node_gateway
node_explorer -->|"invokes read tools"| node_toolkit
node_developer -->|"invokes code tools"| node_toolkit
node_toolkit -->|"checks permissions"| node_policy
node_developer -->|"modifies and tests"| node_workspace
node_reviewer -->|"calls model"| node_gateway
node_reviewer -->|"requests restoration"| node_workspace
node_graph -->|"persists checkpoints"| node_store
node_orchestrator -->|"saves task state"| node_store
node_recovery -->|"checks job state"| node_store
node_orchestrator -->|"prepares PR details"| node_mr_builder
node_orchestrator -->|"requests publication"| node_publisher
node_publisher -->|"creates Draft PR"| node_github
node_user -->|"merges PR"| node_github
node_orchestrator -->|"runs acceptance"| node_ui_validation
node_ui_validation -.->|"reads design context"| node_figma
node_orchestrator -->|"records execution"| node_tracing
node_retrieval_eval -->|"evaluates retrieval"| node_indexer
node_golden_eval -->|"records evaluations"| node_store
node_models -->|"serialized task data"| node_store

click node_api "https://github.com/jeff-jayden/auto_dev_agent/blob/main/apps/api/main.py"
click node_worker "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/execution/worker.py"
click node_orchestrator "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/orchestrator.py"
click node_graph "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/workflow_graph.py"
click node_recovery "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/recovery.py"
click node_models "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/domain/models.py"
click node_store "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/infrastructure/store.py"
click node_repo_analyzer "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/repository/analyzer.py"
click node_repo_catalog "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/repository/catalog.py"
click node_indexer "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/code_intelligence/indexer.py"
click node_planner "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/requirement_planning_agent.py"
click node_explorer "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/repository_exploration_agent.py"
click node_developer "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/code_development_agent.py"
click node_reviewer "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/code_review_agent.py"
click node_mr_builder "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/merge_request_builder.py"
click node_toolkit "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/tools/developer_toolkit.py"
click node_policy "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/tools/policy.py"
click node_workspace "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/sandbox/workspace.py"
click node_gateway "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/llm/gateway.py"
click node_publisher "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/scm/publisher.py"
click node_ui_validation "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/ui_validation.py"
click node_tracing "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/observability/tracing.py"
click node_retrieval_eval "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/evaluation/retrieval.py"
click node_golden_eval "https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/evaluation/golden.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_api,node_worker,node_store,node_user toneBlue
class node_orchestrator,node_graph,node_recovery,node_models toneAmber
class node_repo_analyzer,node_repo_catalog,node_indexer,node_retrieval_eval,node_golden_eval toneMint
class node_planner,node_explorer,node_developer,node_reviewer,node_mr_builder,node_toolkit,node_policy toneRose
class node_workspace,node_gateway,node_publisher,node_ui_validation,node_tracing,node_github,node_figma toneIndigo
```

## Components

### API and execution

- [FastAPI](https://github.com/jeff-jayden/auto_dev_agent/blob/main/apps/api/main.py): `apps/api/main.py`
- [Job worker](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/execution/worker.py): `src/execution/worker.py`
- [SQLite task store](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/infrastructure/store.py): `src/infrastructure/store.py`

### Delivery workflow

- [Task orchestrator](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/orchestrator.py): `src/workflows/orchestrator.py`
- [Delivery graph](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/workflow_graph.py): `src/workflows/workflow_graph.py`
- [Recovery coordinator](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/workflows/recovery.py): `src/workflows/recovery.py`
- [Domain state](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/domain/models.py): `src/domain/models.py`

### Repository intelligence

- [Repository analyzer](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/repository/analyzer.py): `src/repository/analyzer.py`
- [Repository catalog](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/repository/catalog.py): `src/repository/catalog.py`
- [Code indexer](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/code_intelligence/indexer.py): `src/code_intelligence/indexer.py`
- [Retrieval evaluation](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/evaluation/retrieval.py): `src/evaluation/retrieval.py`
- [Golden evaluation](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/evaluation/golden.py): `src/evaluation/golden.py`

### Agents and tools

- [Planning agent](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/requirement_planning_agent.py): `src/agents/requirement_planning_agent.py`
- [Exploration agent](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/repository_exploration_agent.py): `src/agents/repository_exploration_agent.py`
- [Development agent](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/code_development_agent.py): `src/agents/code_development_agent.py`
- [Review agent](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/code_review_agent.py): `src/agents/code_review_agent.py`
- [PR description](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/agents/merge_request_builder.py): `src/agents/merge_request_builder.py`
- [Developer toolkit](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/tools/developer_toolkit.py): `src/tools/developer_toolkit.py`
- [Tool policy](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/tools/policy.py): `src/tools/policy.py`

### Delivery and support

- [Git worktree](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/sandbox/workspace.py): `src/sandbox/workspace.py`
- [Model gateway](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/llm/gateway.py): `src/llm/gateway.py`
- [PR publisher](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/scm/publisher.py): `src/scm/publisher.py`
- [UI acceptance](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/ui_validation.py): `src/ui_validation.py`
- [Tracing](https://github.com/jeff-jayden/auto_dev_agent/blob/main/src/observability/tracing.py): `src/observability/tracing.py`

### Other components

- **User**
- **GitHub**
- **Figma MCP**

## Connections

- User → FastAPI: submits decisions
- FastAPI → Task orchestrator: requests actions
- FastAPI → Job worker: queues jobs
- FastAPI → SQLite task store: reads projections
- Job worker → Task orchestrator: dispatches jobs
- Job worker → SQLite task store: claims and updates
- Job worker → Recovery coordinator: requests recovery
- Task orchestrator → Delivery graph: runs workflow
- Delivery graph → Planning agent: runs planning
- Delivery graph → Exploration agent: requests context
- Delivery graph → Development agent: runs development
- Delivery graph → Review agent: runs review
- Task orchestrator → Repository analyzer: analyzes repository
- Repository analyzer → Repository catalog: uses repository facts
- Repository analyzer → Code indexer: builds retrieval context
- Planning agent → Model gateway: calls model
- Exploration agent → Developer toolkit: invokes read tools
- Development agent → Developer toolkit: invokes code tools
- Developer toolkit → Tool policy: checks permissions
- Development agent → Git worktree: modifies and tests
- Review agent → Model gateway: calls model
- Review agent → Git worktree: requests restoration
- Delivery graph → SQLite task store: persists checkpoints
- Task orchestrator → SQLite task store: saves task state
- Recovery coordinator → SQLite task store: checks job state
- Task orchestrator → PR description: prepares PR details
- Task orchestrator → PR publisher: requests publication
- PR publisher → GitHub: creates Draft PR
- User → GitHub: merges PR
- Task orchestrator → UI acceptance: runs acceptance
- UI acceptance → Figma MCP: reads design context
- Task orchestrator → Tracing: records execution
- Retrieval evaluation → Code indexer: evaluates retrieval
- Golden evaluation → SQLite task store: records evaluations
- Domain state → SQLite task store: serialized task data