# chirag0071/ai-software-engineer architecture

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

- Interactive diagram: https://gitdiagram.com/chirag0071/ai-software-engineer
- Repository: https://github.com/chirag0071/ai-software-engineer

## Overview

This is a FastAPI multi-agent software-engineering service. A user submits a change request and repository path; the workflow analyzes the repository, plans and implements changes, runs tests, retries debugging when needed, and reviews the result. Approval gates GitHub branch and pull-request operations. The graph captures the documented workflow wiring and sampled integrations; several agent implementations and portions of the API are unsampled, so their internal calls are not expanded.

Main entry points: [`backend/graph/workflow.py`](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/graph/workflow.py) (Workflow graph), [`backend/main.py`](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/main.py) (FastAPI API), [`backend/llm.py`](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/llm.py) (LLM clients), [`backend/tools/filesystem.py`](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/filesystem.py) (Safe file access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["FastAPI API<br/>[main.py]"]
  node_auth["JWT auth<br/>[jwt.py]"]
  node_authdeps["Auth dependencies<br/>[dependencies.py]"]
  node_google["Google OAuth<br/>[google.py]"]
  node_roles["Role checks<br/>[roles.py]"]
  node_health["Health check<br/>[health.py]"]
end

subgraph group_workflow["Engineering workflow"]
  node_workflow["Workflow graph<br/>[workflow.py]"]
  node_state["Run state<br/>[state.py]"]
  node_planner["Planner<br/>[planner.py]"]
  node_plan_models["Plan models<br/>[planner_models.py]"]
  node_coder["Coder<br/>[coder.py]"]
  node_tests["Test agent<br/>[test_agent.py]"]
  node_debugger["Debugger<br/>[debugger.py]"]
  node_review["Code review<br/>[code_review.py]"]
  node_approval["Human approval<br/>[human_approval.py]"]
end

subgraph group_repo["Repository tools"]
  node_repository["Repository scan<br/>[repository.py]"]
  node_repo_tool["Repository scanner<br/>[repository.py]"]
  node_intelligence["Repository intelligence"]
  node_filesystem["Safe file access<br/>[filesystem.py]"]
  node_test_runner["Test runner<br/>[test_runner.py]"]
end

subgraph group_integrations["Models and GitHub"]
  node_llm["LLM clients<br/>[llm.py]"]
  node_pr_service["Pull request service<br/>[pr_service.py]"]
  node_github_client["GitHub client<br/>[client.py]"]
end

node_user(("User"))
node_groq(("Groq"))
node_github(("GitHub"))

node_user -->|"submits request"| node_api
node_api -->|"checks identity"| node_authdeps
node_authdeps -->|"verifies token"| node_auth
node_api -->|"offers OAuth"| node_google
node_api -->|"checks roles"| node_roles
node_api -->|"checks health"| node_health
node_api -->|"starts workflow"| node_workflow
node_workflow -->|"dispatches"| node_repository
node_workflow -->|"dispatches"| node_intelligence
node_workflow -->|"dispatches"| node_planner
node_workflow -->|"dispatches"| node_coder
node_workflow -->|"dispatches"| node_tests
node_workflow -->|"dispatches"| node_debugger
node_workflow -->|"dispatches"| node_review
node_workflow -->|"dispatches"| node_approval
node_repository -->|"scans files"| node_repo_tool
node_intelligence -->|"reads files"| node_filesystem
node_review -->|"reads files"| node_filesystem
node_coder -->|"uses file access"| node_filesystem
node_debugger -->|"uses file access"| node_filesystem
node_planner -->|"uses schemas"| node_plan_models
node_tests -.->|"runs tests"| node_test_runner
node_planner -->|"requests model"| node_llm
node_coder -->|"requests model"| node_llm
node_debugger -->|"requests model"| node_llm
node_review -->|"requests model"| node_llm
node_llm -->|"calls API"| node_groq
node_api -.->|"handles approval"| node_pr_service
node_pr_service -->|"operates Git"| node_github_client
node_github_client -->|"calls REST API"| node_github

click node_api "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/main.py"
click node_auth "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/jwt.py"
click node_authdeps "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/dependencies.py"
click node_google "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/google.py"
click node_roles "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/roles.py"
click node_health "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/utils/health.py"
click node_workflow "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/graph/workflow.py"
click node_state "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/graph/state.py"
click node_repository "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/repository.py"
click node_repo_tool "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/repository.py"
click node_intelligence "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/repository_intelligence.py"
click node_planner "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/planner.py"
click node_plan_models "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/planner_models.py"
click node_coder "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/coder.py"
click node_tests "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/test_agent.py"
click node_debugger "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/debugger.py"
click node_review "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/code_review.py"
click node_approval "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/human_approval.py"
click node_filesystem "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/filesystem.py"
click node_test_runner "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/test_runner.py"
click node_llm "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/llm.py"
click node_pr_service "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/github/pr_service.py"
click node_github_client "https://github.com/chirag0071/ai-software-engineer/blob/main/backend/github/client.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_auth,node_authdeps,node_google,node_roles,node_health,node_user toneBlue
class node_workflow,node_state,node_planner,node_plan_models,node_coder,node_tests,node_debugger,node_review,node_approval toneAmber
class node_repository,node_repo_tool,node_intelligence,node_filesystem,node_test_runner toneMint
class node_llm,node_pr_service,node_github_client toneRose
class node_groq,node_github toneIndigo
```

## Components

### API and identity

- [FastAPI API](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/main.py): `backend/main.py`
- [JWT auth](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/jwt.py): `backend/auth/jwt.py`
- [Auth dependencies](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/dependencies.py): `backend/auth/dependencies.py`
- [Google OAuth](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/google.py): `backend/auth/google.py`
- [Role checks](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/auth/roles.py): `backend/auth/roles.py`
- [Health check](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/utils/health.py): `backend/utils/health.py`

### Engineering workflow

- [Workflow graph](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/graph/workflow.py): `backend/graph/workflow.py`
- [Run state](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/graph/state.py): `backend/graph/state.py`
- [Planner](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/planner.py): `backend/agents/planner.py`
- [Plan models](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/planner_models.py): `backend/agents/planner_models.py`
- [Coder](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/coder.py): `backend/agents/coder.py`
- [Test agent](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/test_agent.py): `backend/agents/test_agent.py`
- [Debugger](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/debugger.py): `backend/agents/debugger.py`
- [Code review](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/code_review.py): `backend/agents/code_review.py`
- [Human approval](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/human_approval.py): `backend/agents/human_approval.py`

### Repository tools

- [Repository scan](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/repository.py): `backend/agents/repository.py`
- [Repository scanner](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/repository.py): `backend/tools/repository.py`
- [Repository intelligence](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/agents/repository_intelligence.py): `backend/agents/repository_intelligence.py`
- [Safe file access](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/filesystem.py): `backend/tools/filesystem.py`
- [Test runner](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/tools/test_runner.py): `backend/tools/test_runner.py`

### Models and GitHub

- [LLM clients](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/llm.py): `backend/llm.py`
- [Pull request service](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/github/pr_service.py): `backend/github/pr_service.py`
- [GitHub client](https://github.com/chirag0071/ai-software-engineer/blob/main/backend/github/client.py): `backend/github/client.py`

### Other components

- **User**
- **Groq**
- **GitHub**

## Connections

- User → FastAPI API: submits request (evidence: `backend/main.py`)
- FastAPI API → Auth dependencies: checks identity (evidence: `backend/auth/dependencies.py`)
- Auth dependencies → JWT auth: verifies token (evidence: `backend/auth/dependencies.py`)
- FastAPI API → Google OAuth: offers OAuth (evidence: `backend/main.py`)
- FastAPI API → Role checks: checks roles (evidence: `backend/main.py`)
- FastAPI API → Health check: checks health (evidence: `backend/main.py`)
- FastAPI API → Workflow graph: starts workflow (evidence: `backend/main.py`)
- Workflow graph → Repository scan: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Repository intelligence: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Planner: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Coder: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Test agent: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Debugger: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Code review: dispatches (evidence: `backend/graph/workflow.py`)
- Workflow graph → Human approval: dispatches (evidence: `backend/graph/workflow.py`)
- Repository scan → Repository scanner: scans files (evidence: `backend/agents/repository.py`)
- Repository intelligence → Safe file access: reads files (evidence: `backend/agents/repository_intelligence.py`)
- Code review → Safe file access: reads files (evidence: `backend/agents/code_review.py`)
- Coder → Safe file access: uses file access (evidence: `backend/agents/coder.py`)
- Debugger → Safe file access: uses file access (evidence: `backend/agents/debugger.py`)
- Planner → Plan models: uses schemas (evidence: `backend/agents/planner.py`)
- Test agent → Test runner: runs tests
- Planner → LLM clients: requests model (evidence: `backend/agents/planner.py`)
- Coder → LLM clients: requests model (evidence: `backend/agents/coder.py`)
- Debugger → LLM clients: requests model (evidence: `backend/agents/debugger.py`)
- Code review → LLM clients: requests model (evidence: `backend/agents/code_review.py`)
- LLM clients → Groq: calls API (evidence: `backend/llm.py`)
- FastAPI API → Pull request service: handles approval (evidence: `backend/main.py`)
- Pull request service → GitHub client: operates Git (evidence: `backend/github/pr_service.py`)
- GitHub client → GitHub: calls REST API (evidence: `backend/github/client.py`)
