docs/architecture.md

Architecture

System Overview

┌─────────────┐     ┌─────────────┐     ┌──────────────────┐
│  Gradio UI  │────▶│   FastAPI   │────▶│   Agent Layer    │
│  Port 7860  │     │  Port 8000  │     │                  │
└─────────────┘     └─────────────┘     │  ┌────────────┐  │
                                        │  │ Repo Agent │  │
                                        │  ├────────────┤  │
                                        │  │ Bug Agent  │  │
                                        │  ├────────────┤  │
                                        │  │ Test Agent │  │
                                        │  ├────────────┤  │
                                        │  │ Review     │  │
                                        │  ├────────────┤  │
                                        │  │ Report     │  │
                                        │  └────────────┘  │
                                        └──────────────────┘

Agent Flow

1. User submits GitHub URL via Gradio
2. Gradio sends POST request to FastAPI
3. FastAPI clones repository locally (shallow clone, depth=1)
4. repo_analysis_agent runs first to build repository metadata
5. bug_detection_agent, test_generation_agent, code_review_agent run in parallel via asyncio.gather
6. report_generator_agent aggregates all outputs into a final report
7. Cloned repository is deleted from disk
8. Results displayed in Gradio tabs

Data Flow

RepositoryRequest
      │
      ▼
clone_repository()
      │
      ▼
RepositoryMetadata ──▶ IssueReport ──▶ GeneratedTests ──▶ ReviewSuggestions
      │                    │                 │                    │
      └────────────────────┴─────────────────┴────────────────────┘
                                    │
                                    ▼
                            EngineeringReport

LLM Integration

All agents use OpenRouter API with open source models. Default model: meta-llama/llama-3.3-70b-instruct

Alternative models:

• mistralai/mistral-7b-instruct
• deepseek/deepseek-chat
• google/gemma-3-27b-it

Task queue design

Jobs are routed to one of two Celery queues backed by Redis:

Queue	Threshold	Expected duration
high	repos < 50 MB	< 60 s
low	repos ≥ 50 MB	1–5 min

Workers consume high before low, so a flood of large-repo jobs cannot starve small fast ones. Both queues are durable — a Redis restart does not lose in-flight tasks because task_acks_late=True means a task is only acknowledged after it completes, not on receipt.

Retry policy: up to 2 retries with 60 s / 120 s exponential backoff.