# opti5-labs/medusa architecture

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

- Interactive diagram: https://gitdiagram.com/opti5-labs/medusa
- Repository: https://github.com/opti5-labs/medusa

## Overview

Medusa is a web product for mapping repositories, finding or importing issues, investigating them with independent AI agents, and testing proposed fixes in isolated sandboxes. The main user workflow runs from GitHub or ZIP ingestion through issue scanning and investigation to reproduction, a fix race, and deterministic verification; architecture mapping and repository Q&A are parallel capabilities. The graph combines README-described behavior with sampled imports and calls; unsampled implementation details are represented only where documented, and uncertain internal links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/opti5-labs/medusa/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/scan.py`](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/scan.py) (Scan endpoints), [`backend/app/api/architecture.py`](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/architecture.py) (Architecture endpoints), [`backend/app/api/runs.py`](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/runs.py) (Run endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Next.js pages"]
  node_client["API client<br/>[api.ts]"]
  node_live["Live run streams<br/>[useRunStream.ts]"]
end

subgraph group_entry["API and ingestion"]
  node_ingest_api["Scan endpoints<br/>[scan.py]"]
  node_repo_ingest["GitHub and ZIP ingest"]
  node_github_issues["GitHub issue import<br/>[issues.py]"]
  node_architecture_api["Architecture endpoints<br/>[architecture.py]"]
  node_runs_api["Run endpoints<br/>[runs.py]"]
  node_ask_api["Ask endpoints<br/>[ask.py]"]
end

subgraph group_analysis["Analysis and investigation"]
  node_scan["Issue scanning<br/>[scan.py]"]
  node_architecture["Static architecture map<br/>[architecture.py]"]
  node_arch_engine["Graph and manifests"]
  node_investigation["Investigation pipelines<br/>[debug.py]"]
  node_bob["IBM Bob agent<br/>[bob.py]"]
  node_granite["IBM Granite agent<br/>[granite.py]"]
  node_ask["Repository Q&amp;A<br/>[ask.py]"]
end

subgraph group_proof["Reproduction and verification"]
  node_repro["Reproduction pipeline<br/>[repro.py]"]
  node_sandbox["Isolated runners"]
  node_verify["Deterministic verifier<br/>[verify.py]"]
end

subgraph group_support["Shared services"]
  node_store[("Run and scan store<br/>[store.py]")]
  node_contracts["API contracts<br/>[contracts.py]"]
  node_app["FastAPI application<br/>[main.py]"]
end

node_user(("Repository user"))
node_github["GitHub"]
node_watsonx["watsonx.ai"]
node_gvisor["gVisor sandbox"]
node_docker["Docker demo sandbox"]

node_user -->|"uses"| node_frontend
node_frontend -->|"requests"| node_client
node_frontend -->|"follows events"| node_live
node_client -->|"REST calls"| node_ingest_api
node_frontend -->|"starts map"| node_architecture_api
node_ingest_api -->|"accepts sources"| node_repo_ingest
node_ingest_api -->|"imports issues"| node_github_issues
node_repo_ingest -.->|"fetches repository"| node_github
node_ingest_api -->|"starts scan"| node_scan
node_scan -.->|"scans when needed"| node_bob
node_scan -.->|"scans chunks"| node_granite
node_architecture_api -->|"starts mapping"| node_architecture
node_architecture_api -->|"uses store"| node_store
node_architecture_api -->|"uses schemas"| node_contracts
node_runs_api -.->|"runs debug"| node_investigation
node_investigation -.->|"requests diagnosis"| node_bob
node_investigation -.->|"requests diagnosis"| node_granite
node_granite -->|"calls model"| node_watsonx
node_runs_api -.->|"starts reproduction"| node_repro
node_repro -->|"runs test"| node_sandbox
node_sandbox -->|"runs linked repos"| node_gvisor
node_sandbox -->|"runs demo"| node_docker
node_runs_api -.->|"selects fix"| node_verify
node_ask_api -->|"answers questions"| node_ask
node_ask_api -.->|"may consult"| node_bob
node_ask_api -.->|"may consult"| node_granite
node_app -->|"registers router"| node_ingest_api
node_app -->|"registers router"| node_runs_api
node_app -->|"registers router"| node_ask_api
node_app -->|"registers router"| node_architecture_api
node_app -->|"starts store"| node_store
node_client -->|"REST and SSE"| node_runs_api
node_client -.->|"REST calls"| node_ask_api
node_architecture -.->|"builds map"| node_arch_engine

click node_frontend "https://github.com/opti5-labs/medusa/tree/main/frontend/app"
click node_client "https://github.com/opti5-labs/medusa/blob/main/frontend/lib/api.ts"
click node_live "https://github.com/opti5-labs/medusa/blob/main/frontend/lib/useRunStream.ts"
click node_ingest_api "https://github.com/opti5-labs/medusa/blob/main/backend/app/api/scan.py"
click node_repo_ingest "https://github.com/opti5-labs/medusa/tree/main/backend/app/ingest"
click node_github_issues "https://github.com/opti5-labs/medusa/blob/main/backend/app/github/issues.py"
click node_scan "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/scan.py"
click node_architecture_api "https://github.com/opti5-labs/medusa/blob/main/backend/app/api/architecture.py"
click node_architecture "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/architecture.py"
click node_arch_engine "https://github.com/opti5-labs/medusa/tree/main/backend/app/architecture"
click node_runs_api "https://github.com/opti5-labs/medusa/blob/main/backend/app/api/runs.py"
click node_investigation "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/debug.py"
click node_bob "https://github.com/opti5-labs/medusa/blob/main/backend/app/agents/bob.py"
click node_granite "https://github.com/opti5-labs/medusa/blob/main/backend/app/agents/granite.py"
click node_repro "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/repro.py"
click node_sandbox "https://github.com/opti5-labs/medusa/tree/main/backend/app/sandbox"
click node_verify "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/verify.py"
click node_ask_api "https://github.com/opti5-labs/medusa/blob/main/backend/app/api/ask.py"
click node_ask "https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/ask.py"
click node_store "https://github.com/opti5-labs/medusa/blob/main/backend/app/store.py"
click node_contracts "https://github.com/opti5-labs/medusa/blob/main/backend/app/models/contracts.py"
click node_app "https://github.com/opti5-labs/medusa/blob/main/backend/app/main.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_frontend,node_client,node_live,node_user toneBlue
class node_ingest_api,node_repo_ingest,node_github_issues,node_architecture_api,node_runs_api,node_ask_api toneAmber
class node_scan,node_architecture,node_arch_engine,node_investigation,node_bob,node_granite,node_ask toneMint
class node_repro,node_sandbox,node_verify toneRose
class node_store,node_contracts,node_app,node_github,node_watsonx,node_gvisor,node_docker toneIndigo
```

## Components

### Web interface

- [Next.js pages](https://github.com/opti5-labs/medusa/tree/main/frontend/app): `frontend/app`
- [API client](https://github.com/opti5-labs/medusa/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Live run streams](https://github.com/opti5-labs/medusa/blob/main/frontend/lib/useRunStream.ts): `frontend/lib/useRunStream.ts`

### API and ingestion

- [Scan endpoints](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/scan.py): `backend/app/api/scan.py`
- [GitHub and ZIP ingest](https://github.com/opti5-labs/medusa/tree/main/backend/app/ingest): `backend/app/ingest`
- [GitHub issue import](https://github.com/opti5-labs/medusa/blob/main/backend/app/github/issues.py): `backend/app/github/issues.py`
- [Architecture endpoints](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/architecture.py): `backend/app/api/architecture.py`
- [Run endpoints](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/runs.py): `backend/app/api/runs.py`
- [Ask endpoints](https://github.com/opti5-labs/medusa/blob/main/backend/app/api/ask.py): `backend/app/api/ask.py`

### Analysis and investigation

- [Issue scanning](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/scan.py): `backend/app/pipelines/scan.py`
- [Static architecture map](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/architecture.py): `backend/app/pipelines/architecture.py`
- [Graph and manifests](https://github.com/opti5-labs/medusa/tree/main/backend/app/architecture): `backend/app/architecture`
- [Investigation pipelines](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/debug.py): `backend/app/pipelines/debug.py`
- [IBM Bob agent](https://github.com/opti5-labs/medusa/blob/main/backend/app/agents/bob.py): `backend/app/agents/bob.py`
- [IBM Granite agent](https://github.com/opti5-labs/medusa/blob/main/backend/app/agents/granite.py): `backend/app/agents/granite.py`
- [Repository Q&A](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/ask.py): `backend/app/pipelines/ask.py`

### Reproduction and verification

- [Reproduction pipeline](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/repro.py): `backend/app/pipelines/repro.py`
- [Isolated runners](https://github.com/opti5-labs/medusa/tree/main/backend/app/sandbox): `backend/app/sandbox`
- [Deterministic verifier](https://github.com/opti5-labs/medusa/blob/main/backend/app/pipelines/verify.py): `backend/app/pipelines/verify.py`

### Shared services

- [Run and scan store](https://github.com/opti5-labs/medusa/blob/main/backend/app/store.py): `backend/app/store.py`
- [API contracts](https://github.com/opti5-labs/medusa/blob/main/backend/app/models/contracts.py): `backend/app/models/contracts.py`
- [FastAPI application](https://github.com/opti5-labs/medusa/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Repository user**
- **GitHub**
- **watsonx.ai**
- **gVisor sandbox**
- **Docker demo sandbox**

## Connections

- Repository user → Next.js pages: uses (evidence: `README.md`)
- Next.js pages → API client: requests (evidence: `frontend/app/scan/github/page.tsx`)
- Next.js pages → Live run streams: follows events (evidence: `frontend/app/investigate/[id]/page.tsx`)
- API client → Scan endpoints: REST calls (evidence: `README.md`)
- Next.js pages → Architecture endpoints: starts map
- Scan endpoints → GitHub and ZIP ingest: accepts sources (evidence: `backend/app/api/scan.py`)
- Scan endpoints → GitHub issue import: imports issues (evidence: `backend/app/api/scan.py`)
- GitHub and ZIP ingest → GitHub: fetches repository (evidence: `README.md`)
- Scan endpoints → Issue scanning: starts scan (evidence: `backend/app/api/scan.py`)
- Issue scanning → IBM Bob agent: scans when needed (evidence: `README.md`)
- Issue scanning → IBM Granite agent: scans chunks (evidence: `README.md`)
- Architecture endpoints → Static architecture map: starts mapping (evidence: `backend/app/api/architecture.py`)
- Architecture endpoints → Run and scan store: uses store (evidence: `backend/app/api/architecture.py`)
- Architecture endpoints → API contracts: uses schemas (evidence: `backend/app/api/architecture.py`)
- Run endpoints → Investigation pipelines: runs debug (evidence: `README.md`)
- Investigation pipelines → IBM Bob agent: requests diagnosis (evidence: `README.md`)
- Investigation pipelines → IBM Granite agent: requests diagnosis (evidence: `README.md`)
- IBM Granite agent → watsonx.ai: calls model (evidence: `README.md`)
- Run endpoints → Reproduction pipeline: starts reproduction (evidence: `README.md`)
- Reproduction pipeline → Isolated runners: runs test (evidence: `README.md`)
- Isolated runners → gVisor sandbox: runs linked repos (evidence: `README.md`)
- Isolated runners → Docker demo sandbox: runs demo (evidence: `README.md`)
- Run endpoints → Deterministic verifier: selects fix (evidence: `README.md`)
- Ask endpoints → Repository Q&A: answers questions (evidence: `backend/app/api/ask.py`)
- Ask endpoints → IBM Bob agent: may consult (evidence: `backend/app/api/ask.py`)
- Ask endpoints → IBM Granite agent: may consult (evidence: `backend/app/api/ask.py`)
- FastAPI application → Scan endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Run endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Ask endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Architecture endpoints: registers router (evidence: `backend/app/main.py`)
- FastAPI application → Run and scan store: starts store (evidence: `backend/app/main.py`)
- API client → Run endpoints: REST and SSE (evidence: `README.md`)
- API client → Ask endpoints: REST calls (evidence: `README.md`)
- Static architecture map → Graph and manifests: builds map (evidence: `README.md`)