# mdayanabbas/repopilot architecture

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

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

## Overview

#### Purpose and Runtime
RepoPilot is a local-first Python 3.11+ backend that analyzes local or Git-backed FastAPI/Flask repositories and produces LLM-assisted, schema-validated debugging fix plans. Its ASGI entry point is `backend/app/main.py`; versioned HTTP endpoints are assembled through `backend/app/api/router.py` and `backend/app/api/v1/`.

#### API and Orchestration Boundary
HTTP route modules expose repository loading, analysis history/runs, architecture, fix-plan, LLM, health, and trace operations. Workflows coordinate the long-running business sequence rather than embedding it in API handlers:
- `backend/app/api/v1/routes_analysis.py`
- `backend/app/workflows/analyze_repository_workflow.py`
- `backend/app/workflows/generate_fix_plan_workflow.py`

Analysis produces separate persisted `analysis_run_id` and observability `trace_run_id`, which clients use for result/history versus trace lookup.

#### Repository Ingestion and Workspace Isolation
Repository services load either a local directory or Git source into managed workspace storage, record metadata, and clean up workspace state. This is the boundary between untrusted target repositories and RepoPilot’s analysis pipeline:
- `backend/app/repository/service.py`
- `backend/app/repository/workspace.py`
- `backend/app/repository/git_client.py`

Target source is then scanned for eligible files, ignored paths, language, file roles, and supported framework signals:
- `backend/app/scanner/service.py`
- `backend/app/scanner/framework_detector.py`
- `backend/app/scanner/file_tree.py`

#### Static Code Intelligence and Graphs
Python AST parsing extracts imports, functions, classes, symbols, and framework routes. FastAPI/Flask-specific extractors convert target code into route-level intelligence; import and symbol indexes support downstream retrieval.
- `backend/app/intelligence/service.py`
- `backend/app/intelligence/python_ast_parser.py`
- `backend/app/intelligence/fastapi_extractor.py`
- `backend/app/intelligence/flask_extractor.py`

Architecture construction derives dependency/layer relationships and exports JSON or Mermaid. A separate knowledge graph models debugging relationships through explicit nodes and edges:
- `backend/app/architecture/service.py`
- `backend/app/architecture/architecture_graph.py`
- `backend/app/knowledge_graph/service.py`

#### Issue-Focused Retrieval and Context
Given an issue, retrieval combines keyword, import, route, and Git-history signals; scoring and token budgeting select a bounded context for the model. Git intelligence analyzes log, blame, and change frequency and can boost relevant code.
- `backend/app/retrieval/service.py`
- `backend/app/retrieval/context_builder.py`
- `backend/app/retrieval/git_retriever.py`
- `backend/app/git_intelligence/service.py`

This establishes a key boundary: deterministic repository analysis and retrieval happen before external model invocation.

#### LLM Fix-Plan Generation
The agent layer builds prompts from retrieved context, selects a configured provider, calls it, parses the response, and validates it against structured schemas before returning/persisting a fix plan. Providers support remote Groq and local LM Studio:
- `backend/app/agent/service.py`
- `backend/app/agent/provider_factory.py`
- `backend/app/agent/providers/groq_provider.py`
- `backend/app/agent/providers/lmstudio_provider.py`
- `backend/app/agent/schema_validator.py`

Prompt and output-contract assets live outside executable code:
- `prompts/system/repopilot_system_prompt.md`
- `prompts/fix_plan/fastapi_fix_plan_prompt.md`
- `prompts/schemas/fix_plan_schema.json`

#### Persistence, Observability, and Deployment
SQLAlchemy-style database/session/repository layers persist repositories, analyses, retrieval outputs, plans, traces, and graphs; Alembic owns migrations. SQLite is the stated default, while Docker Compose infrastructure includes PostgreSQL and Redis assets.
- `backend/app/database/models.py`
- `backend/app/database/repositories.py`
- `backend/alembic/env.py`
- `docker-compose.yml`

Trace context and event/model/tool loggers capture workflow execution independently of API responses:
- `backend/app/tracing/service.py`
- `backend/app/tracing/event_logger.py`
- `backend/app/tracing/model_call_logger.py`

Container deployment is defined by `infra/Dockerfile.backend` and `infra/nginx.conf`.

Main entry points: [`backend/app/workflows/generate_fix_plan_workflow.py`](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/generate_fix_plan_workflow.py) (Fix-plan workflow), [`backend/app/workflows/analyze_repository_workflow.py`](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/analyze_repository_workflow.py) (Repository analysis workflow), [`backend/app/agent/service.py`](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/agent/service.py) (Fix-plan agent), [`backend/app/api/v1/routes_analysis.py`](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/api/v1/routes_analysis.py) (Analysis routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API & workflows"]
  node_asgi["ASGI application<br/>FastAPI entry point<br/>[main.py]"]
  node_router["Versioned API router<br/>route assembly<br/>[router.py]"]
  node_analysis_routes["Analysis routes<br/>HTTP handlers<br/>[routes_analysis.py]"]
  node_analysis_workflow["Repository analysis workflow"]
  node_fixplan_workflow["Fix-plan workflow"]
end

subgraph group_ingestion["Repository analysis"]
  node_repository_service["Repository workspace service<br/>ingestion service<br/>[service.py]"]
  node_scanner["Source scanner<br/>repository scanner<br/>[service.py]"]
  node_intelligence["Static code intelligence<br/>AST analysis<br/>[service.py]"]
  node_architecture["Architecture graph builder<br/>architecture service<br/>[service.py]"]
  node_knowledge_graph["Debugging knowledge graph<br/>graph service<br/>[service.py]"]
end

subgraph group_retrieval["Retrieval & planning"]
  node_retrieval_service["Issue retrieval<br/>retrieval service<br/>[service.py]"]
  node_context_builder["Bounded model context<br/>context builder<br/>[context_builder.py]"]
  node_git_intelligence["Git intelligence<br/>history analysis<br/>[service.py]"]
  node_agent["Fix-plan agent<br/>LLM orchestration<br/>[service.py]"]
  node_providers["LLM provider factory<br/>provider selection"]
  node_prompt_contract["Fix-plan contract<br/>prompt and schema assets"]
end

subgraph group_platform["Persistence & operations"]
  node_database[("Database repositories<br/>persistence layer<br/>[repositories.py]")]
  node_tracing["Trace service<br/>observability<br/>[service.py]"]
  node_migrations["Alembic migrations<br/>schema migration<br/>[env.py]"]
  node_deployment["Container deployment<br/>Docker build<br/>[Dockerfile.backend]"]
end

node_asgi -->|"mounts"| node_router
node_router -->|"dispatches"| node_analysis_routes
node_analysis_routes -->|"starts analysis"| node_analysis_workflow
node_analysis_routes -->|"requests plan"| node_fixplan_workflow
node_analysis_workflow -->|"loads source"| node_repository_service
node_repository_service -->|"provides workspace"| node_scanner
node_scanner -->|"eligible source files"| node_intelligence
node_intelligence -->|"symbols and imports"| node_architecture
node_intelligence -->|"code relationships"| node_knowledge_graph
node_analysis_workflow -->|"persists analysis run"| node_database
node_analysis_workflow -->|"creates trace run"| node_tracing
node_fixplan_workflow -->|"retrieves issue evidence"| node_retrieval_service
node_retrieval_service -->|"ranked candidates"| node_context_builder
node_git_intelligence -->|"history signals"| node_retrieval_service
node_context_builder -->|"bounded context"| node_agent
node_fixplan_workflow -->|"generates plan"| node_agent
node_agent -->|"selects provider"| node_providers
node_agent -->|"uses output contract"| node_prompt_contract
node_fixplan_workflow -->|"persists fix plan"| node_database
node_fixplan_workflow -->|"logs model execution"| node_tracing
node_migrations -->|"evolves schema"| node_database
node_deployment -.->|"containers runtime"| node_asgi

click node_asgi "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/main.py"
click node_router "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/api/router.py"
click node_analysis_routes "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/api/v1/routes_analysis.py"
click node_analysis_workflow "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/analyze_repository_workflow.py"
click node_fixplan_workflow "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/generate_fix_plan_workflow.py"
click node_repository_service "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/repository/service.py"
click node_scanner "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/scanner/service.py"
click node_intelligence "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/intelligence/service.py"
click node_architecture "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/architecture/service.py"
click node_knowledge_graph "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/knowledge_graph/service.py"
click node_retrieval_service "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/retrieval/service.py"
click node_context_builder "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/retrieval/context_builder.py"
click node_git_intelligence "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/git_intelligence/service.py"
click node_agent "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/agent/service.py"
click node_providers "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/agent/provider_factory.py"
click node_prompt_contract "https://github.com/mdayanabbas/repopilot/blob/main/prompts/schemas/fix_plan_schema.json"
click node_database "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/database/repositories.py"
click node_tracing "https://github.com/mdayanabbas/repopilot/blob/main/backend/app/tracing/service.py"
click node_migrations "https://github.com/mdayanabbas/repopilot/blob/main/backend/alembic/env.py"
click node_deployment "https://github.com/mdayanabbas/repopilot/blob/main/infra/Dockerfile.backend"

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_asgi,node_router,node_analysis_routes,node_analysis_workflow,node_fixplan_workflow toneBlue
class node_repository_service,node_scanner,node_intelligence,node_architecture,node_knowledge_graph toneAmber
class node_retrieval_service,node_context_builder,node_git_intelligence,node_agent,node_providers,node_prompt_contract toneMint
class node_database,node_tracing,node_migrations,node_deployment toneRose
```

## Components

### API & workflows

- [ASGI application](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/main.py): FastAPI entry point · `backend/app/main.py`
- [Versioned API router](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/api/router.py): route assembly · `backend/app/api/router.py`
- [Analysis routes](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/api/v1/routes_analysis.py): HTTP handlers · `backend/app/api/v1/routes_analysis.py`
- [Repository analysis workflow](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/analyze_repository_workflow.py): workflow · Coordinates loading, scanning, intelligence, and persisted analysis runs. · `backend/app/workflows/analyze_repository_workflow.py`
- [Fix-plan workflow](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/workflows/generate_fix_plan_workflow.py): workflow · Separates deterministic retrieval from model invocation. · `backend/app/workflows/generate_fix_plan_workflow.py`

### Repository analysis

- [Repository workspace service](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/repository/service.py): ingestion service · Loads local or Git sources into isolated managed workspaces. · `backend/app/repository/service.py`
- [Source scanner](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/scanner/service.py): repository scanner · Filters files and detects languages, roles, and supported frameworks. · `backend/app/scanner/service.py`
- [Static code intelligence](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/intelligence/service.py): AST analysis · Extracts symbols, imports, and framework routes. · `backend/app/intelligence/service.py`
- [Architecture graph builder](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/architecture/service.py): architecture service · Derives dependency and layer relationships for JSON or Mermaid export. · `backend/app/architecture/service.py`
- [Debugging knowledge graph](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/knowledge_graph/service.py): graph service · `backend/app/knowledge_graph/service.py`

### Retrieval & planning

- [Issue retrieval](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/retrieval/service.py): retrieval service · Combines keyword, import, route, and history signals. · `backend/app/retrieval/service.py`
- [Bounded model context](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/retrieval/context_builder.py): context builder · Scores evidence and applies token budgeting. · `backend/app/retrieval/context_builder.py`
- [Git intelligence](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/git_intelligence/service.py): history analysis · Uses log, blame, and change frequency to boost relevance. · `backend/app/git_intelligence/service.py`
- [Fix-plan agent](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/agent/service.py): LLM orchestration · Builds prompts, calls a provider, parses, and validates plans. · `backend/app/agent/service.py`
- [LLM provider factory](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/agent/provider_factory.py): provider selection · Selects remote Groq or local LM Studio. · `backend/app/agent/provider_factory.py`
- [Fix-plan contract](https://github.com/mdayanabbas/repopilot/blob/main/prompts/schemas/fix_plan_schema.json): prompt and schema assets · `prompts/schemas/fix_plan_schema.json`

### Persistence & operations

- [Database repositories](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/database/repositories.py): persistence layer · Persists repositories, runs, retrieval outputs, plans, traces, and graphs. · `backend/app/database/repositories.py`
- [Trace service](https://github.com/mdayanabbas/repopilot/blob/main/backend/app/tracing/service.py): observability · Records trace runs independently of analysis results. · `backend/app/tracing/service.py`
- [Alembic migrations](https://github.com/mdayanabbas/repopilot/blob/main/backend/alembic/env.py): schema migration · `backend/alembic/env.py`
- [Container deployment](https://github.com/mdayanabbas/repopilot/blob/main/infra/Dockerfile.backend): Docker build · `infra/Dockerfile.backend`

## Connections

- ASGI application → Versioned API router: mounts
- Versioned API router → Analysis routes: dispatches
- Analysis routes → Repository analysis workflow: starts analysis
- Analysis routes → Fix-plan workflow: requests plan
- Repository analysis workflow → Repository workspace service: loads source
- Repository workspace service → Source scanner: provides workspace
- Source scanner → Static code intelligence: eligible source files
- Static code intelligence → Architecture graph builder: symbols and imports
- Static code intelligence → Debugging knowledge graph: code relationships
- Repository analysis workflow → Database repositories: persists analysis run
- Repository analysis workflow → Trace service: creates trace run
- Fix-plan workflow → Issue retrieval: retrieves issue evidence
- Issue retrieval → Bounded model context: ranked candidates
- Git intelligence → Issue retrieval: history signals
- Bounded model context → Fix-plan agent: bounded context
- Fix-plan workflow → Fix-plan agent: generates plan
- Fix-plan agent → LLM provider factory: selects provider
- Fix-plan agent → Fix-plan contract: uses output contract
- Fix-plan workflow → Database repositories: persists fix plan
- Fix-plan workflow → Trace service: logs model execution
- Alembic migrations → Database repositories: evolves schema
- Container deployment → ASGI application: containers runtime