How opti5-labs/medusa works
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: main.py FastAPI application · scan.py Scan endpoints · architecture.py Architecture endpoints · runs.py Run endpoints
Components 27
Web interface
- Next.js pages
frontend/app - API client
frontend/lib/api.ts - Live run streams
frontend/lib/useRunStream.ts
API and ingestion
- Scan endpoints
backend/app/api/scan.py - GitHub and ZIP ingest
backend/app/ingest - GitHub issue import
backend/app/github/issues.py - Architecture endpoints
backend/app/api/architecture.py - Run endpoints
backend/app/api/runs.py - Ask endpoints
backend/app/api/ask.py
Analysis and investigation
- Issue scanning
backend/app/pipelines/scan.py - Static architecture map
backend/app/pipelines/architecture.py - Graph and manifests
backend/app/architecture - Investigation pipelines
backend/app/pipelines/debug.py - IBM Bob agent
backend/app/agents/bob.py - IBM Granite agent
backend/app/agents/granite.py - Repository Q&A
backend/app/pipelines/ask.py
Reproduction and verification
- Reproduction pipeline
backend/app/pipelines/repro.py - Isolated runners
backend/app/sandbox - Deterministic verifier
backend/app/pipelines/verify.py
Shared services
- Run and scan store
backend/app/store.py - API contracts
backend/app/models/contracts.py - FastAPI application
backend/app/main.py
Other components
- Repository user
- GitHub
- watsonx.ai
- gVisor sandbox
- Docker demo sandbox
Connections 34
- Repository user → Next.js pages: uses
README.md - Next.js pages → API client: requests
frontend/app/scan/github/page.tsx - Next.js pages → Live run streams: follows events
frontend/app/investigate/[id]/page.tsx - API client → Scan endpoints: REST calls
README.md - Next.js pages → Architecture endpoints: starts map
- Scan endpoints → GitHub and ZIP ingest: accepts sources
backend/app/api/scan.py - Scan endpoints → GitHub issue import: imports issues
backend/app/api/scan.py - GitHub and ZIP ingest → GitHub: fetches repository
README.md - Scan endpoints → Issue scanning: starts scan
backend/app/api/scan.py - Issue scanning → IBM Bob agent: scans when needed
README.md - Issue scanning → IBM Granite agent: scans chunks
README.md - Architecture endpoints → Static architecture map: starts mapping
backend/app/api/architecture.py - Architecture endpoints → Run and scan store: uses store
backend/app/api/architecture.py - Architecture endpoints → API contracts: uses schemas
backend/app/api/architecture.py - Run endpoints → Investigation pipelines: runs debug
README.md - Investigation pipelines → IBM Bob agent: requests diagnosis
README.md - Investigation pipelines → IBM Granite agent: requests diagnosis
README.md - IBM Granite agent → watsonx.ai: calls model
README.md - Run endpoints → Reproduction pipeline: starts reproduction
README.md - Reproduction pipeline → Isolated runners: runs test
README.md - Isolated runners → gVisor sandbox: runs linked repos
README.md - Isolated runners → Docker demo sandbox: runs demo
README.md - Run endpoints → Deterministic verifier: selects fix
README.md - Ask endpoints → Repository Q&A: answers questions
backend/app/api/ask.py - Ask endpoints → IBM Bob agent: may consult
backend/app/api/ask.py - Ask endpoints → IBM Granite agent: may consult
backend/app/api/ask.py - FastAPI application → Scan endpoints: registers router
backend/app/main.py - FastAPI application → Run endpoints: registers router
backend/app/main.py - FastAPI application → Ask endpoints: registers router
backend/app/main.py - FastAPI application → Architecture endpoints: registers router
backend/app/main.py - FastAPI application → Run and scan store: starts store
backend/app/main.py - API client → Run endpoints: REST and SSE
README.md - API client → Ask endpoints: REST calls
README.md - Static architecture map → Graph and manifests: builds map
README.md