# aayushii-code/repopilot architecture

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

- Interactive diagram: https://gitdiagram.com/aayushii-code/repopilot
- Repository: https://github.com/aayushii-code/repopilot

## Overview

RepoPilot accepts a repository and task, then runs a background workflow that validates the request, resolves and clones the repository, inspects and profiles its files, ranks relevant files, and asks a configured model for a grounded implementation plan. Users can follow run state and streamed events through the API, WebSocket, or terminal UI. The README describes later editing, test diagnosis/retry, and pull-request capabilities as future work; they are not implemented in the current status. Source excerpts are partial, so uncertain internal links are omitted.

Main entry points: [`backend/repopilot/execution/engine.py`](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/engine.py) (Run engine), [`backend/repopilot/api/runs.py`](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/api/runs.py) (Runs API), [`backend/repopilot/execution/steps.py`](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/steps.py) (Pipeline steps), [`backend/repopilot/main.py`](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/main.py) (Application setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_terminal["Terminal UI<br/>[App.tsx]"]
  node_frontend_api["Frontend API<br/>[api.ts]"]
  node_stream_hook["Run stream hook<br/>[useRunStream.ts]"]
end

subgraph group_api["Run management"]
  node_http_api["Runs API<br/>[runs.py]"]
  node_websocket["WebSocket stream<br/>[ws.py]"]
  node_run_model["Run models<br/>[models.py]"]
  node_repository_ref["Repository reference<br/>[repository.py]"]
  node_run_store[("Run and event store<br/>[store.py]")]
  node_app_setup["Application setup<br/>[main.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_execution["Execution and discovery"]
  node_engine["Run engine<br/>[engine.py]"]
  node_pipeline["Pipeline steps<br/>[steps.py]"]
  node_event_bus["Event bus<br/>[bus.py]"]
  node_github_client["GitHub client<br/>[client.py]"]
  node_profile["Repository profile<br/>[profile.py]"]
  node_relevance["File relevance ranking<br/>[relevance.py]"]
end

subgraph group_reasoning["Planning and providers"]
  node_plan["Implementation planning<br/>[plan.py]"]
  node_llm_client["LLM client<br/>[llm.py]"]
end

node_user(("User"))
node_github["GitHub"]
node_model_provider["Model provider"]

node_user -->|"submits task"| node_terminal
node_terminal -->|"calls API"| node_frontend_api
node_terminal -->|"subscribes to stream"| node_stream_hook
node_frontend_api -->|"requests run endpoints"| node_http_api
node_stream_hook -->|"opens event stream"| node_websocket
node_http_api -->|"reads and writes runs"| node_run_store
node_http_api -->|"starts run"| node_engine
node_http_api -->|"normalizes repository"| node_repository_ref
node_http_api -->|"uses run model"| node_run_model
node_websocket -->|"replays events"| node_run_store
node_websocket -->|"subscribes live"| node_event_bus
node_app_setup -->|"registers routes"| node_http_api
node_app_setup -->|"loads configuration"| node_settings
node_app_setup -->|"configures store"| node_run_store
node_app_setup -->|"configures engine"| node_engine
node_engine -->|"updates run state"| node_run_store
node_engine -->|"publishes events"| node_event_bus
node_engine -->|"executes steps"| node_pipeline
node_engine -->|"tracks run status"| node_run_model
node_pipeline -->|"resolves repository"| node_github_client
node_github_client -->|"fetches repository metadata"| node_github
node_pipeline -->|"profiles checkout"| node_profile
node_pipeline -->|"ranks candidate files"| node_relevance
node_pipeline -->|"creates implementation plan"| node_plan
node_plan -->|"grounds plan"| node_profile
node_plan -->|"uses file shortlist"| node_relevance
node_plan -->|"requests completion"| node_llm_client
node_llm_client -->|"sends model request"| node_model_provider
node_engine -->|"configures collaborators"| node_settings

click node_terminal "https://github.com/aayushii-code/repopilot/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/aayushii-code/repopilot/blob/main/frontend/src/api.ts"
click node_stream_hook "https://github.com/aayushii-code/repopilot/blob/main/frontend/src/useRunStream.ts"
click node_http_api "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/api/runs.py"
click node_websocket "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/api/ws.py"
click node_run_model "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/models.py"
click node_repository_ref "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/repository.py"
click node_run_store "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/store.py"
click node_app_setup "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/main.py"
click node_engine "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/engine.py"
click node_pipeline "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/steps.py"
click node_event_bus "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/bus.py"
click node_github_client "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/github/client.py"
click node_profile "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/analysis/profile.py"
click node_relevance "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/analysis/relevance.py"
click node_plan "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/agent/plan.py"
click node_llm_client "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/agent/llm.py"
click node_settings "https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/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_terminal,node_frontend_api,node_stream_hook,node_user toneBlue
class node_http_api,node_websocket,node_run_model,node_repository_ref,node_run_store,node_app_setup,node_settings toneAmber
class node_engine,node_pipeline,node_event_bus,node_github_client,node_profile,node_relevance toneMint
class node_plan,node_llm_client toneRose
class node_github,node_model_provider toneIndigo
```

## Components

### User interfaces

- [Terminal UI](https://github.com/aayushii-code/repopilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Frontend API](https://github.com/aayushii-code/repopilot/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Run stream hook](https://github.com/aayushii-code/repopilot/blob/main/frontend/src/useRunStream.ts): `frontend/src/useRunStream.ts`

### Run management

- [Runs API](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/api/runs.py): `backend/repopilot/api/runs.py`
- [WebSocket stream](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/api/ws.py): `backend/repopilot/api/ws.py`
- [Run models](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/models.py): `backend/repopilot/domain/models.py`
- [Repository reference](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/repository.py): `backend/repopilot/domain/repository.py`
- [Run and event store](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/domain/store.py): `backend/repopilot/domain/store.py`
- [Application setup](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/main.py): `backend/repopilot/main.py`
- [Runtime settings](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/config.py): `backend/repopilot/config.py`

### Execution and discovery

- [Run engine](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/engine.py): `backend/repopilot/execution/engine.py`
- [Pipeline steps](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/steps.py): `backend/repopilot/execution/steps.py`
- [Event bus](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/execution/bus.py): `backend/repopilot/execution/bus.py`
- [GitHub client](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/github/client.py): `backend/repopilot/github/client.py`
- [Repository profile](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/analysis/profile.py): `backend/repopilot/analysis/profile.py`
- [File relevance ranking](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/analysis/relevance.py): `backend/repopilot/analysis/relevance.py`

### Planning and providers

- [Implementation planning](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/agent/plan.py): `backend/repopilot/agent/plan.py`
- [LLM client](https://github.com/aayushii-code/repopilot/blob/main/backend/repopilot/agent/llm.py): `backend/repopilot/agent/llm.py`

### Other components

- **User**
- **GitHub**
- **Model provider**

## Connections

- User → Terminal UI: submits task (evidence: `README.md`)
- Terminal UI → Frontend API: calls API (evidence: `frontend/src/App.tsx`)
- Terminal UI → Run stream hook: subscribes to stream (evidence: `frontend/src/App.tsx`)
- Frontend API → Runs API: requests run endpoints (evidence: `README.md`)
- Run stream hook → WebSocket stream: opens event stream (evidence: `README.md`)
- Runs API → Run and event store: reads and writes runs (evidence: `backend/repopilot/api/runs.py`)
- Runs API → Run engine: starts run (evidence: `backend/repopilot/api/runs.py`)
- Runs API → Repository reference: normalizes repository (evidence: `backend/repopilot/api/runs.py`)
- Runs API → Run models: uses run model (evidence: `backend/repopilot/api/runs.py`)
- WebSocket stream → Run and event store: replays events (evidence: `backend/repopilot/api/ws.py`)
- WebSocket stream → Event bus: subscribes live (evidence: `backend/repopilot/api/ws.py`)
- Application setup → Runs API: registers routes (evidence: `backend/repopilot/main.py`)
- Application setup → Runtime settings: loads configuration (evidence: `backend/repopilot/main.py`)
- Application setup → Run and event store: configures store (evidence: `backend/repopilot/main.py`)
- Application setup → Run engine: configures engine (evidence: `backend/repopilot/main.py`)
- Run engine → Run and event store: updates run state (evidence: `backend/repopilot/execution/engine.py`)
- Run engine → Event bus: publishes events (evidence: `backend/repopilot/execution/engine.py`)
- Run engine → Pipeline steps: executes steps (evidence: `backend/repopilot/execution/engine.py`)
- Run engine → Run models: tracks run status (evidence: `backend/repopilot/execution/engine.py`)
- Pipeline steps → GitHub client: resolves repository (evidence: `backend/repopilot/execution/steps.py`)
- GitHub client → GitHub: fetches repository metadata (evidence: `backend/repopilot/github/client.py`)
- Pipeline steps → Repository profile: profiles checkout (evidence: `backend/repopilot/execution/steps.py`)
- Pipeline steps → File relevance ranking: ranks candidate files (evidence: `backend/repopilot/execution/steps.py`)
- Pipeline steps → Implementation planning: creates implementation plan (evidence: `backend/repopilot/execution/steps.py`)
- Implementation planning → Repository profile: grounds plan (evidence: `backend/repopilot/agent/plan.py`)
- Implementation planning → File relevance ranking: uses file shortlist (evidence: `backend/repopilot/agent/plan.py`)
- Implementation planning → LLM client: requests completion (evidence: `backend/repopilot/agent/plan.py`)
- LLM client → Model provider: sends model request (evidence: `backend/repopilot/agent/llm.py`)
- Run engine → Runtime settings: configures collaborators (evidence: `backend/repopilot/execution/engine.py`)
