# abanteai/repo-visualizer architecture

> Architecture diagram of the GitHub repository abanteai/repo-visualizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abanteai/repo-visualizer
- Repository: https://github.com/abanteai/repo-visualizer

## Overview

#### 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: [`frontend/src/App.tsx`](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/App.tsx) (Visualization app), [`src/repo_visualizer/analyzer.py`](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/analyzer.py) (Repository analyzer), [`src/repo_visualizer/schema.py`](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/schema.py) (Output schema), [`frontend/src/components/Visualization/RepositoryGraph.tsx`](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/Visualization/RepositoryGraph.tsx) (Interactive graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python analyzer"]
  node_cli["CLI entry point<br/>Python CLI<br/>[cli.py]"]
  node_module_entry["Module entry point<br/>Python entry<br/>[__main__.py]"]
  node_analyzer["Repository analyzer<br/>analysis pipeline<br/>[analyzer.py]"]
  node_example_python["Example support<br/>example data<br/>[example.py]"]
  node_package_surface["Package surface<br/>Python package<br/>[__init__.py]"]
end

subgraph group_contract["Data contract"]
  node_python_schema["Output schema<br/>Python model<br/>[schema.py]"]
  node_schema_docs["Schema documentation<br/>[SCHEMA.md]"]
  node_json_artifact["Repository JSON<br/>file artifact"]
end

subgraph group_frontend["Browser UI"]
  node_frontend_schema["Frontend schema types<br/>TypeScript types<br/>[schema.ts]"]
  node_visualization_types["Visualization model<br/>TypeScript types<br/>[visualization.ts]"]
  node_frontend_boot["Frontend bootstrap<br/>Vite entry<br/>[main.tsx]"]
  node_app["Visualization app<br/>application coordinator<br/>[App.tsx]"]
  node_file_upload["JSON file upload<br/>ingestion UI<br/>[FileUpload.tsx]"]
  node_graph_renderer["Interactive graph<br/>graph renderer"]
  node_visualization_utils["Display transforms<br/>presentation utilities"]
  node_graph_controls["Graph controls<br/>control UI<br/>[NodeControls.tsx]"]
  node_file_details["File details<br/>detail UI<br/>[FileDetails.tsx]"]
end

subgraph group_runtime["Runtime &amp; validation"]
  node_launcher{{"Local launcher<br/>shell orchestration<br/>[start_project.sh]"}}
  node_vite["Vite development server<br/>frontend build runtime<br/>[vite.config.ts]"]
  node_python_ci["Python checks<br/>CI workflow<br/>[python-checks.yml]"]
  node_frontend_ci["Frontend checks<br/>CI workflow"]
end

node_module_entry -->|"invokes"| node_cli
node_cli -->|"runs"| node_analyzer
node_package_surface -->|"exposes"| node_analyzer
node_example_python -.->|"supports examples"| node_analyzer
node_analyzer -->|"builds"| node_python_schema
node_python_schema -->|"serializes as"| node_json_artifact
node_python_schema -.->|"documented by"| node_schema_docs
node_python_schema -->|"mirrored by"| node_frontend_schema
node_frontend_schema -->|"maps into"| node_visualization_types
node_frontend_boot -->|"boots"| node_app
node_json_artifact -->|"loaded locally"| node_file_upload
node_file_upload -->|"supplies data"| node_app
node_app -->|"renders through"| node_graph_renderer
node_visualization_types -->|"drives graph model"| node_graph_renderer
node_visualization_utils -->|"transforms display"| node_graph_renderer
node_graph_controls -->|"adjusts client view"| node_graph_renderer
node_app -->|"shows selection"| node_file_details
node_launcher -->|"generates artifact"| node_cli
node_launcher -->|"starts"| node_vite
node_vite -->|"serves"| node_frontend_boot
node_python_ci -.->|"validates"| node_analyzer
node_frontend_ci -.->|"validates"| node_app

click node_cli "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/cli.py"
click node_module_entry "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/__main__.py"
click node_analyzer "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/analyzer.py"
click node_example_python "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/example.py"
click node_package_surface "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/__init__.py"
click node_python_schema "https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/schema.py"
click node_schema_docs "https://github.com/abanteai/repo-visualizer/blob/main/docs/SCHEMA.md"
click node_frontend_schema "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/types/schema.ts"
click node_visualization_types "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/types/visualization.ts"
click node_frontend_boot "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/main.tsx"
click node_app "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/App.tsx"
click node_file_upload "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/FileUpload.tsx"
click node_graph_renderer "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/Visualization/RepositoryGraph.tsx"
click node_visualization_utils "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/utils/visualizationUtils.ts"
click node_graph_controls "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/NodeControls.tsx"
click node_file_details "https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/FileDetails.tsx"
click node_launcher "https://github.com/abanteai/repo-visualizer/blob/main/start_project.sh"
click node_vite "https://github.com/abanteai/repo-visualizer/blob/main/frontend/vite.config.ts"
click node_python_ci "https://github.com/abanteai/repo-visualizer/blob/main/.github/workflows/python-checks.yml"
click node_frontend_ci "https://github.com/abanteai/repo-visualizer/blob/main/.github/workflows/frontend-checks.yml"

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_cli,node_module_entry,node_analyzer,node_example_python,node_package_surface toneBlue
class node_python_schema,node_schema_docs,node_json_artifact toneAmber
class node_frontend_schema,node_visualization_types,node_frontend_boot,node_app,node_file_upload,node_graph_renderer,node_visualization_utils,node_graph_controls,node_file_details toneMint
class node_launcher,node_vite,node_python_ci,node_frontend_ci toneRose
```

## Components

### Python analyzer

- [CLI entry point](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/cli.py): Python CLI · `src/repo_visualizer/cli.py`
- [Module entry point](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/__main__.py): Python entry · `src/repo_visualizer/__main__.py`
- [Repository analyzer](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/analyzer.py): analysis pipeline · Traverses source, code relationships, language data, and Git history. · `src/repo_visualizer/analyzer.py`
- [Example support](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/example.py): example data · `src/repo_visualizer/example.py`
- [Package surface](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/__init__.py): Python package · `src/repo_visualizer/__init__.py`

### Data contract

- [Output schema](https://github.com/abanteai/repo-visualizer/blob/main/src/repo_visualizer/schema.py): Python model · `src/repo_visualizer/schema.py`
- [Schema documentation](https://github.com/abanteai/repo-visualizer/blob/main/docs/SCHEMA.md): documentation · `docs/SCHEMA.md`
- **Repository JSON**: file artifact · The offline boundary between analysis and browser rendering.

### Browser UI

- [Frontend schema types](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/types/schema.ts): TypeScript types · `frontend/src/types/schema.ts`
- [Visualization model](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/types/visualization.ts): TypeScript types · `frontend/src/types/visualization.ts`
- [Frontend bootstrap](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/main.tsx): Vite entry · `frontend/src/main.tsx`
- [Visualization app](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/App.tsx): application coordinator · `frontend/src/App.tsx`
- [JSON file upload](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/FileUpload.tsx): ingestion UI · `frontend/src/components/FileUpload.tsx`
- [Interactive graph](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/Visualization/RepositoryGraph.tsx): graph renderer · `frontend/src/components/Visualization/RepositoryGraph.tsx`
- [Display transforms](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/utils/visualizationUtils.ts): presentation utilities · `frontend/src/utils/visualizationUtils.ts`
- [Graph controls](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/NodeControls.tsx): control UI · Node, edge, weighting, and floating control composition. · `frontend/src/components/NodeControls.tsx`
- [File details](https://github.com/abanteai/repo-visualizer/blob/main/frontend/src/components/FileDetails.tsx): detail UI · `frontend/src/components/FileDetails.tsx`

### Runtime & validation

- [Local launcher](https://github.com/abanteai/repo-visualizer/blob/main/start_project.sh): shell orchestration · Generates data and starts the frontend development server. · `start_project.sh`
- [Vite development server](https://github.com/abanteai/repo-visualizer/blob/main/frontend/vite.config.ts): frontend build runtime · `frontend/vite.config.ts`
- [Python checks](https://github.com/abanteai/repo-visualizer/blob/main/.github/workflows/python-checks.yml): CI workflow · `.github/workflows/python-checks.yml`
- [Frontend checks](https://github.com/abanteai/repo-visualizer/blob/main/.github/workflows/frontend-checks.yml): CI workflow · `.github/workflows/frontend-checks.yml`

## Connections

- 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
