mdayanabbas/repopilot

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.