# dakshjain-1616/orbit-dependency-visualised architecture

> Architecture diagram of the GitHub repository dakshjain-1616/orbit-dependency-visualised, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dakshjain-1616/orbit-dependency-visualised
- Repository: https://github.com/dakshjain-1616/orbit-dependency-visualised

## Overview

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`](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py) (Analysis Pipeline), [`neo_parser.py`](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py) (Parser Engine), [`static/index.html`](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html) (Browser SPA), [`save_analysis.py`](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/save_analysis.py) (Snapshot Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_spa["Browser SPA<br/>3d viewer<br/>[index.html]"]
  node_repo_loader["Repo Loader<br/>ui input<br/>[index.html]"]
  node_graph_view(("Graph View<br/>renderer<br/>[index.html]"))
  node_inspect_controls["Inspect Controls<br/>ui state<br/>[index.html]"]
end

subgraph group_backend["Backend"]
  node_api_service["API Service<br/>web app<br/>[main.py]"]
  node_analyze_route["Analyze Route<br/>endpoint<br/>[main.py]"]
  node_chat_route["Chat Route<br/>endpoint<br/>[main.py]"]
  node_demo_route["Demo Route<br/>endpoint<br/>[main.py]"]
  node_repo_fetcher["Repo Fetcher<br/>clone/fetch<br/>[main.py]"]
  node_analysis_pipeline["Analysis Pipeline<br/>orchestrator<br/>[main.py]"]
  node_sse_stream["SSE Stream<br/>progress stream<br/>[main.py]"]
  node_parser_engine["Parser Engine<br/>tree-sitter<br/>[neo_parser.py]"]
  node_language_adapters["Language Adapters<br/>parsers<br/>[neo_parser.py]"]
  node_symbol_graph["Symbol Graph<br/>structure extractor<br/>[neo_parser.py]"]
  node_metrics_engine["Metrics Engine<br/>[neo_parser.py]"]
  node_architecture_model["Arch Model<br/>schema<br/>[main.py]"]
  node_insight_detector["Insight Detector<br/>heuristics<br/>[main.py]"]
end

subgraph group_external["External"]
  node_anthropic_claude{{"Claude<br/>ai service"}}
end

subgraph group_tooling["Tooling"]
  node_snapshot_builder["Snapshot Builder<br/>offline export<br/>[save_analysis.py]"]
end

node_repo_loader -->|"load repo"| node_analyze_route
node_browser_spa -->|"render"| node_graph_view
node_browser_spa -->|"interact"| node_inspect_controls
node_api_service -->|"exposes"| node_analyze_route
node_api_service -->|"exposes"| node_chat_route
node_api_service -->|"exposes"| node_demo_route
node_analyze_route -->|"fetch"| node_repo_fetcher
node_analyze_route -->|"orchestrate"| node_analysis_pipeline
node_analysis_pipeline -->|"parse"| node_parser_engine
node_parser_engine -->|"supports"| node_language_adapters
node_parser_engine -->|"extract"| node_symbol_graph
node_parser_engine -->|"measure"| node_metrics_engine
node_analysis_pipeline -->|"normalize"| node_architecture_model
node_analysis_pipeline -->|"infer"| node_insight_detector
node_architecture_model -->|"stream"| node_sse_stream
node_chat_route -->|"query"| node_anthropic_claude
node_demo_route -->|"serve snapshot"| node_snapshot_builder
node_snapshot_builder -->|"export"| node_architecture_model
node_browser_spa -->|"request"| node_api_service

click node_browser_spa "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html"
click node_repo_loader "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html"
click node_graph_view "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html"
click node_inspect_controls "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html"
click node_api_service "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_analyze_route "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_chat_route "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_demo_route "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_repo_fetcher "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_analysis_pipeline "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_sse_stream "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_parser_engine "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py"
click node_language_adapters "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py"
click node_symbol_graph "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py"
click node_metrics_engine "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py"
click node_architecture_model "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_insight_detector "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py"
click node_snapshot_builder "https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/save_analysis.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_browser_spa,node_repo_loader,node_graph_view,node_inspect_controls toneBlue
class node_api_service,node_analyze_route,node_chat_route,node_demo_route,node_repo_fetcher,node_analysis_pipeline,node_sse_stream,node_parser_engine,node_language_adapters,node_symbol_graph,node_metrics_engine,node_architecture_model,node_insight_detector toneAmber
class node_anthropic_claude toneMint
class node_snapshot_builder toneRose
```

## Components

### Frontend

Browser-side visualization and interaction layer

- [Browser SPA](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html): 3d viewer · Vanilla JS frontend that renders the dependency graph and handles interaction · `static/index.html`
- [Repo Loader](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html): ui input · Takes a repository URL and branch from the user and drives loading · `static/index.html`
- [Graph View](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html): renderer · 3D force-graph visualization built on 3d-force-graph and Three.js · `static/index.html`
- [Inspect Controls](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/static/index.html): ui state · Node inspection, focus mode, filters, camera controls, and local history · `static/index.html`

### Backend

Python service that analyzes repositories and serves results

- [API Service](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): web app · FastAPI-style service boundary exposing analysis, chat, and demo endpoints · `main.py`
- [Analyze Route](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): endpoint · Receives repo URL and branch, kicks off analysis, and streams progress · `main.py`
- [Chat Route](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): endpoint · Answers architecture questions using the analyzed repository graph · `main.py`
- [Demo Route](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): endpoint · Serves a prebuilt analysis snapshot for static demo usage · `main.py`
- [Repo Fetcher](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): clone/fetch · Retrieves the target GitHub repository source for analysis · `main.py`
- [Analysis Pipeline](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): orchestrator · Coordinates parsing, normalization, metrics, and result assembly · `main.py`
- [SSE Stream](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): progress stream · Streams analysis progress and final payload back to the browser · `main.py`
- [Parser Engine](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py): tree-sitter · Tree-sitter based code understanding engine for multiple languages · `neo_parser.py`
- [Language Adapters](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py): parsers · Supports Python, JavaScript/TypeScript, Go, Rust, and Java · `neo_parser.py`
- [Symbol Graph](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py): structure extractor · Extracts AST structure, exported symbols, files, and module relationships · `neo_parser.py`
- [Metrics Engine](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/neo_parser.py): metrics · Computes lines of code, function/class counts, and complexity signals · `neo_parser.py`
- [Arch Model](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): schema · Normalizes analysis into repository-agnostic nodes, edges, metrics, and insights · `main.py`
- [Insight Detector](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/main.py): heuristics · Flags coupling, cycles, and god-module style hotspots · `main.py`

### External

Outside systems the app depends on

- **Claude**: ai service · External LLM used only for the chat endpoint

### Tooling

Offline snapshot generation and deployment packaging

- [Snapshot Builder](https://github.com/dakshjain-1616/orbit-dependency-visualised/blob/main/save_analysis.py): offline export · Generates prebuilt analysis data for the demo path · `save_analysis.py`

## Connections

- 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