How abanteai/repo-visualizer works
Purpose and Entry Points
Repo Visualizer analyzes a local Git repository into a structured JSON graph model, then renders that model in a browser-based interactive graph UI. Primary entry points are the Python module/CLI in src/repo_visualizer/__main__.py and src/repo_visualizer/cli.py, plus the integrated local launcher start_project.sh. The frontend boots from frontend/src/main.tsx into frontend/src/App.tsx.
Analyzer Pipeline
The repository-analysis boundary is centered on src/repo_visualizer/analyzer.py. It traverses repository content, extracts file metadata, imports/references, code components, language statistics, and Git-history information, then produces visualization-consumable JSON. src/repo_visualizer/example.py provides example-oriented execution/data support, while src/repo_visualizer/__init__.py exposes the package surface.
Shared Data Contract
src/repo_visualizer/schema.py defines the analyzer’s structured output model, documented externally in docs/SCHEMA.md. The frontend mirrors this contract through frontend/src/types/schema.ts and maps graph-specific representations in frontend/src/types/visualization.ts. JSON is the principal integration boundary: the Python process writes an artifact and the frontend loads it; there is no indicated backend API or persistent service.
Frontend Ingestion and Application State
frontend/src/App.tsx coordinates the visualization experience. frontend/src/components/FileUpload.tsx is the local JSON-file ingestion path, and frontend/src/components/FileDetails.tsx presents selected-file information. Example/demo data can be loaded from frontend/src/utils/exampleData.ts. This keeps repository analysis separate from browser rendering and permits visualizing previously generated output files.
Graph Rendering and Interaction
The core renderer is frontend/src/components/Visualization/RepositoryGraph.tsx, exposed via frontend/src/components/Visualization/index.ts. It consumes normalized repository/visualization data to render files and relationships as an interactive graph. Display semantics and transformations are concentrated in frontend/src/utils/visualizationUtils.ts and frontend/src/utils/extensionColors.ts, separating graph presentation from analyzer output.
Visualization Controls
Graph behavior is controlled by focused UI components: frontend/src/components/NodeControls.tsx, frontend/src/components/EdgeControls.tsx, and frontend/src/components/DataSourceWeights.tsx. Additional floating/menu composition is implemented by frontend/src/components/FloatingMenu.tsx and frontend/src/components/DraggableControls.tsx. These controls alter client-side rendering/layout attributes rather than modifying source repository data.
Runtime, Infrastructure, and External Dependencies
The analyzer runs as an installable Python package configured by pyproject.toml and setup.py, requiring access to a local filesystem and Git repository/history. The UI is a TypeScript frontend under frontend/, built and served with Vite (frontend/vite.config.ts) and Node/npm. start_project.sh bridges the two runtimes by generating repository data and starting the frontend development server. CI separates Python and frontend validation in .github/workflows/python-checks.yml and .github/workflows/frontend-checks.yml.
Main entry points: App.tsx Visualization app · analyzer.py Repository analyzer · schema.py Output schema · RepositoryGraph.tsx Interactive graph
Components 21
Python analyzer
- CLI entry point
src/repo_visualizer/cli.py - Module entry point
src/repo_visualizer/__main__.py - Repository analyzer · Traverses source, code relationships, language data, and Git history.
src/repo_visualizer/analyzer.py - Example support
src/repo_visualizer/example.py - Package surface
src/repo_visualizer/__init__.py
Data contract
- Output schema
src/repo_visualizer/schema.py - Schema documentation
docs/SCHEMA.md - Repository JSON · The offline boundary between analysis and browser rendering.
Browser UI
- Frontend schema types
frontend/src/types/schema.ts - Visualization model
frontend/src/types/visualization.ts - Frontend bootstrap
frontend/src/main.tsx - Visualization app
frontend/src/App.tsx - JSON file upload
frontend/src/components/FileUpload.tsx - Interactive graph
frontend/src/components/Visualization/RepositoryGraph.tsx - Display transforms
frontend/src/utils/visualizationUtils.ts - Graph controls · Node, edge, weighting, and floating control composition.
frontend/src/components/NodeControls.tsx - File details
frontend/src/components/FileDetails.tsx
Runtime & validation
- Local launcher · Generates data and starts the frontend development server.
start_project.sh - Vite development server
frontend/vite.config.ts - Python checks
.github/workflows/python-checks.yml - Frontend checks
.github/workflows/frontend-checks.yml
Connections 22
- Module entry point → CLI entry point: invokes
- CLI entry point → Repository analyzer: runs
- Package surface → Repository analyzer: exposes
- Example support → Repository analyzer: supports examples
- Repository analyzer → Output schema: builds
- Output schema → Repository JSON: serializes as
- Output schema → Schema documentation: documented by
- Output schema → Frontend schema types: mirrored by
- Frontend schema types → Visualization model: maps into
- Frontend bootstrap → Visualization app: boots
- Repository JSON → JSON file upload: loaded locally
- JSON file upload → Visualization app: supplies data
- Visualization app → Interactive graph: renders through
- Visualization model → Interactive graph: drives graph model
- Display transforms → Interactive graph: transforms display
- Graph controls → Interactive graph: adjusts client view
- Visualization app → File details: shows selection
- Local launcher → CLI entry point: generates artifact
- Local launcher → Vite development server: starts
- Vite development server → Frontend bootstrap: serves
- Python checks → Repository analyzer: validates
- Frontend checks → Visualization app: validates