How rohityadav483/repo2arch works
1. What this repo is
Repo2Arch is a two-tier application that takes a public GitHub repository URL, clones and analyzes the code on the backend, then presents diagrams and summaries in a Streamlit frontend. The core architectural boundary is between the UI layer and the analysis API.
2. Frontend subsystem
The frontend/ app is a Streamlit single-page interface. It collects the GitHub URL, calls the backend through frontend/utils/api_client.py, and renders four result types through separate components: architecture diagram, dependency graph, AI summary, and tech stack badges. This layer is presentation-only and does not perform code analysis itself.
3. Backend API boundary
The backend/app/ package is a FastAPI service exposing versioned endpoints under /api/v1. backend/app/main.py wires the application together, while backend/app/api/routes.py hosts the public endpoints for health checks, analysis requests, history lookup, and cached repo retrieval. models/schemas.py defines the request/response contract between frontend and backend.
4. Analysis pipeline
A repo analysis request flows through a sequence of services: fetch the repository, inspect files, extract structural metadata, build graph representations, generate Mermaid text, optionally generate an AI summary, then persist and return the result. This pipeline is the main backend workflow and is designed to be reusable across API calls and cached history reads.
5. Repository ingestion
backend/app/services/github_fetcher.py is responsible for obtaining source code from GitHub public repositories, typically by cloning into a temporary local workspace. The temp_clones/ directory in the repo reflects this working-set concept: cloned repositories are treated as transient analysis inputs, not long-lived application assets.
6. Code understanding and tech detection
backend/app/services/code_analyzer.py performs static inspection using AST plus regex-based heuristics. It identifies languages, frameworks, entry points, tests, CI/Docker indicators, and other repo-level signals. These extracted facts feed both the diagram builders and the summary/insight outputs.
7. Graph and diagram generation
backend/app/services/graph_builder.py constructs a file-level dependency graph, likely using NetworkX as the underlying graph model. backend/app/services/mermaid_generator.py converts that structure into Mermaid graph TD syntax for the architecture diagram. The frontend then renders the Mermaid output and an interactive graph view, giving two different visualizations of the same analyzed structure.
8. AI summary subsystem
backend/app/services/ai_summary.py sends only structured metadata, not raw source code, to Hugging Face Inference API models. The README indicates a primary model plus fallbacks, so the AI layer is an external dependency with graceful degradation rather than a local ML runtime. Its job is to produce a human-readable architecture explanation and improvement suggestions from the extracted repo facts.
9. Persistence and caching
backend/app/services/supabase_client.py stores and retrieves analyses from Supabase. The persisted schema includes an analyses table for repo-level metadata and a diagrams table for generated graph artifacts. This creates a caching boundary: repeated analyses for the same repository can be served from storage instead of recloning and reprocessing.
10. Configuration and operational concerns
backend/app/config.py centralizes environment-driven settings such as the Hugging Face key, Supabase credentials, debug mode, and clone directory. backend/app/utils/helpers.py likely holds shared utility logic used across services. The deployment shape is simple: FastAPI backend on Python 3.11+ and a separate Streamlit frontend, both configured through environment variables and communicating over HTTP.
Main entry points: routes.py API routes · app.py Streamlit app · config.py Config · github_fetcher.py Repo fetcher
Components 19
Frontend
Streamlit presentation layer
- Streamlit app · Main Streamlit entrypoint for collecting repo URLs and showing results
frontend/app.py - API client · Calls backend analysis endpoints from the UI
frontend/utils/api_client.py - Diagram view · Renders architecture diagram output in the UI
frontend/components/diagram_view.py - Graph view · Shows interactive dependency graph results
frontend/components/graph_view.py - Summary view · Displays AI-generated architecture summary
frontend/components/summary_view.py - Tech badges · Shows detected languages and framework badges
frontend/components/tech_badges.py
Backend
FastAPI analysis service
- API app · Wires the backend application and middleware
backend/app/main.py - API routes · Public versioned endpoints for health, analysis, history, and cached repos
backend/app/api/routes.py - Schemas · Request and response models shared by the frontend and backend
backend/app/models/schemas.py - Repo fetcher · Clones public GitHub repositories into a temporary workspace
backend/app/services/github_fetcher.py - Code analyzer · Extracts repo signals with AST and heuristics
backend/app/services/code_analyzer.py - Graph builder · Builds file-level dependency graph structure
backend/app/services/graph_builder.py - Mermaid gen · Converts graph data into Mermaid syntax
backend/app/services/mermaid_generator.py - AI summary · Generates human-readable summary from structured repo metadata
backend/app/services/ai_summary.py - Supabase store · Stores analyses and generated diagrams for caching and history
backend/app/services/supabase_client.py - Config · Environment-driven backend settings and secrets
backend/app/config.py - Helpers · Common utility functions used across backend services
backend/app/utils/helpers.py
External services
Third-party APIs and storage
- Hugging Face · External inference API used for summaries
Workspace
Transient cloned repositories
- Temp clones · Transient local clone workspace for analyzed repositories
temp_clones
Connections 23
- Streamlit app → API client: submits URL · UI sends repository URL and requests analysis
- Streamlit app → Diagram view: renders · Displays generated architecture diagram
- Streamlit app → Graph view: renders · Displays dependency graph visualization
- Streamlit app → Summary view: renders · Displays AI summary output
- Streamlit app → Tech badges: renders · Displays detected technology badges
- API client → API routes: calls API · Sends analysis and history requests over HTTP
- API app → API routes: mounts · Registers the versioned route handlers
- API routes → Schemas: uses contracts · Validates request and response payloads
- API routes → Repo fetcher: fetches repo · Starts repository ingestion for analysis
- API routes → Code analyzer: analyzes code · Extracts language, framework, and structural signals
- API routes → Graph builder: builds graph · Creates dependency graph artifacts
- API routes → Mermaid gen: generates diagram · Produces Mermaid representation for the frontend
- API routes → AI summary: summarizes · Creates a human-readable explanation from structured metadata
- API routes → Supabase store: persists · Stores and retrieves analysis results and diagrams
- Code analyzer → Helpers: uses · Shares utility logic for inspection and parsing
- Graph builder → Helpers: uses · Shares utility logic for graph construction
- AI summary → Hugging Face: calls · Uses external inference models with fallback behavior
- Repo fetcher → Temp clones: writes clones · Creates transient local workspaces for source repositories
- Repo fetcher → Config: reads settings · Uses clone directory and related environment configuration
- Supabase store → Config: reads settings · Uses credentials and database configuration
- API app → Config: loads config · Initializes service behavior from environment settings
- API routes → Helpers: uses · Shares common backend utility functions
- Streamlit app → Config: reads env · Frontend is configured through environment variables