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.