How dakshjain-1616/orbit-dependency-visualised works
1. Repository purpose
- Orbis is a two-part system: a Python backend that analyzes a GitHub repository’s source code structure, and a browser SPA that renders the result as an interactive 3D dependency graph.
2. Top-level boundaries
- main.py is the service boundary and API surface.
- neo_parser.py is the code-understanding engine.
- static/index.html is the entire frontend application.
- save_analysis.py is an offline utility for generating demo analysis data.
3. Backend request flow
- The client submits a GitHub repo URL and optional branch to /analyze.
- The backend clones or fetches the target repository, parses it, computes architecture metadata, and streams progress/results back as Server-Sent Events.
- The final payload is a complete graph model containing nodes, edges, metrics, and detected issues.
4. Analysis subsystem
- The parser is tree-sitter based and supports multiple languages: Python, JavaScript/TypeScript, Go, Rust, and Java.
- Its role is to extract AST-level structure, exported symbols, file/module relationships, and per-file metrics such as lines of code and counts of functions/classes.
5. Graph model produced by analysis
- The analysis output is normalized into a repository-agnostic architecture schema.
- Nodes represent modules/files with metadata like language, complexity, and dependencies.
- Edges represent import or dependency relationships.
- Insights capture architectural findings such as high coupling, circular dependencies, and “god module” style hotspots.
6. Frontend rendering layer
- The SPA in static/index.html consumes the analysis output and renders the codebase using 3d-force-graph and Three.js.
- It is a no-build, vanilla JavaScript frontend, so the browser directly owns the visualization and interaction logic.
- The UI supports node inspection, focus mode, filters, camera controls, and URL-driven repo loading.
7. AI chat subsystem
- /chat is a separate backend path that sends the analyzed architecture context to Anthropic Claude.
- The assistant is grounded in the repository graph, not raw source text alone, so its answers are about dependency structure, refactoring priorities, and architectural relationships.
- If ANTHROPIC_API_KEY is missing, the feature degrades gracefully rather than blocking the rest of the app.
8. Demo and offline support
- /demo serves a prebuilt analysis snapshot instead of requiring a live GitHub clone.
- save_analysis.py exists to regenerate that snapshot data from a repository ahead of time.
- This creates a clean separation between live analysis and static demo consumption.
9. State and persistence
- The backend appears stateless between requests; the main durable artifact is the analysis payload returned to the browser.
- Recent repository history is kept locally in the browser, not in a server database.
- There is no evidence of a persistent server-side datastore or queue.
10. Deployment/runtime shape
- The application runs as a Python web service, typically via Uvicorn serving the FastAPI app.
- The provided Dockerfile packages the same backend plus static UI for containerized deployment.
- .env.example documents environment configuration, especially the Anthropic key used by chat.
11. What to draw in an architecture diagram
- Show a browser SPA at the edge calling three backend endpoints: analyze, chat, and demo.
- Show the backend as the orchestrator that invokes repository cloning, tree-sitter parsing, architecture inference, and SSE streaming.
- Show Anthropic as an external dependency only for the chat path.
- Show the demo utility as an offline producer of cached analysis snapshots.
12. Key architectural characteristic
- The system is analysis-first and streaming-oriented: the expensive work happens on the backend, while the frontend is a thin interactive renderer of the computed graph.
Main entry points: main.py Analysis Pipeline · neo_parser.py Parser Engine · index.html Browser SPA · save_analysis.py Snapshot Builder
Components 19
Frontend
Browser-side visualization and interaction layer
- Browser SPA · Vanilla JS frontend that renders the dependency graph and handles interaction
static/index.html - Repo Loader · Takes a repository URL and branch from the user and drives loading
static/index.html - Graph View · 3D force-graph visualization built on 3d-force-graph and Three.js
static/index.html - Inspect Controls · Node inspection, focus mode, filters, camera controls, and local history
static/index.html
Backend
Python service that analyzes repositories and serves results
- API Service · FastAPI-style service boundary exposing analysis, chat, and demo endpoints
main.py - Analyze Route · Receives repo URL and branch, kicks off analysis, and streams progress
main.py - Chat Route · Answers architecture questions using the analyzed repository graph
main.py - Demo Route · Serves a prebuilt analysis snapshot for static demo usage
main.py - Repo Fetcher · Retrieves the target GitHub repository source for analysis
main.py - Analysis Pipeline · Coordinates parsing, normalization, metrics, and result assembly
main.py - SSE Stream · Streams analysis progress and final payload back to the browser
main.py - Parser Engine · Tree-sitter based code understanding engine for multiple languages
neo_parser.py - Language Adapters · Supports Python, JavaScript/TypeScript, Go, Rust, and Java
neo_parser.py - Symbol Graph · Extracts AST structure, exported symbols, files, and module relationships
neo_parser.py - Metrics Engine · Computes lines of code, function/class counts, and complexity signals
neo_parser.py - Arch Model · Normalizes analysis into repository-agnostic nodes, edges, metrics, and insights
main.py - Insight Detector · Flags coupling, cycles, and god-module style hotspots
main.py
External
Outside systems the app depends on
- Claude · External LLM used only for the chat endpoint
Tooling
Offline snapshot generation and deployment packaging
- Snapshot Builder · Generates prebuilt analysis data for the demo path
save_analysis.py
Connections 19
- Repo Loader → Analyze Route: load repo · User submits a repository URL and branch to begin analysis
- Browser SPA → Graph View: render · The SPA renders the computed architecture graph
- Browser SPA → Inspect Controls: interact · UI supports inspection, focus, filtering, and camera control
- API Service → Analyze Route: exposes · Analyze endpoint is part of the backend API surface
- API Service → Chat Route: exposes · Chat endpoint is part of the backend API surface
- API Service → Demo Route: exposes · Demo endpoint serves cached analysis data
- Analyze Route → Repo Fetcher: fetch · Backend clones or fetches the target repository
- Analyze Route → Analysis Pipeline: orchestrate · Analyze route hands off work to the analysis pipeline
- Analysis Pipeline → Parser Engine: parse · Pipeline invokes the code-understanding engine
- Parser Engine → Language Adapters: supports · Tree-sitter parsing spans multiple languages
- Parser Engine → Symbol Graph: extract · Parser extracts structure, symbols, and module relationships
- Parser Engine → Metrics Engine: measure · Parser computes per-file metrics and complexity signals
- Analysis Pipeline → Arch Model: normalize · Pipeline converts raw analysis into the repo-agnostic schema
- Analysis Pipeline → Insight Detector: infer · Pipeline derives architectural findings from the parsed graph
- Arch Model → SSE Stream: stream · Final graph model and progress updates are streamed to the client
- Chat Route → Claude: query · Chat sends architecture context to Claude for grounded answers
- Demo Route → Snapshot Builder: serve snapshot · Demo path returns prebuilt analysis output
- Snapshot Builder → Arch Model: export · Offline utility regenerates the analysis snapshot artifact
- Browser SPA → API Service: request · Frontend calls backend endpoints for analysis, chat, and demo