# juspay/codetraverse architecture

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

- Interactive diagram: https://gitdiagram.com/juspay/codetraverse
- Repository: https://github.com/juspay/codetraverse

## Overview

1. **Repository shape**
   CODETRAVERSE is primarily a Python static-analysis engine, with a separate TypeScript/Node bridge for invoking it from JavaScript consumers. The Python side owns parsing, component extraction, graph construction, and file outputs; the bridge is a thin integration layer.

2. **Main execution entry points**
   The top-level `main.py` is the primary CLI for analyzing a repository, while `path.py` is a second CLI for querying the generated graph. The Python package also has `codetraverse/main.py`, which appears to be the internal module entry point behind the root script.

3. **Analysis pipeline**
   The core flow is: walk a source repository, detect the target language, parse each file, extract structural components and dependencies, serialize per-file summaries, then unify everything into a global dependency graph. This is a read-only analysis pipeline; it does not modify the analyzed codebase.

4. **Language-specific front ends**
   Support is split across per-language modules in `codetraverse/extractors/` and `codetraverse/adapters/` for Haskell, ReScript, TypeScript, Rust, Go, and Python. The extractors likely perform language-aware AST/component extraction, while the adapters normalize those results into the common internal model.

5. **Shared component model**
   `codetraverse/base/component_extractor.py` and `codetraverse/registry/extractor_registry.py` indicate a central abstraction layer that maps files/languages to the right extractor implementation. This is the main boundary that keeps the rest of the system language-agnostic.

6. **Graph construction and storage**
   `codetraverse/utils/networkx_graph.py` and `codetraverse/utils/graph_partitioner.py` suggest the extracted dependencies are assembled into a NetworkX graph. The outputs described in the README are `GraphML` for interoperability and `gpickle` for Python-native reuse.

7. **Per-file JSON artifacts**
   The `fdep/` output directory contains one JSON summary per source file. These files are the intermediate, file-scoped representation of extracted components before they are unified into the repo-wide graph.

8. **Diff and impact-analysis subsystem**
   The `codetraverse/ast_diff/` package contains language-specific diff logic, plus shared helpers like `basefilediff.py`, `Detailedchanges.py`, and integration with Git/Bitbucket wrappers. This is a separate analysis path focused on comparing AST-level changes and likely feeding impact or change-tracking workflows.

9. **Repository traversal and path utilities**
   `codetraverse/path.py` and `codetraverse/utils/blackbox.py` indicate utility layers for repo path handling and graph query operations. The README’s path CLI uses these outputs to answer shortest-path and neighborhood queries over the dependency graph.

10. **Node/TypeScript bridge**
   The `bridge/` directory is a standalone TypeScript package with its own tests and a `python-runner` abstraction. Architecturally, it wraps the Python engine so JS/TS callers can launch analyses without embedding Python logic directly.

11. **Fixture-driven validation**
   `sample_code_repo_test/` contains small example repositories in the supported languages, used to validate extraction behavior across language boundaries. The `tests/` tree mirrors the package structure, with focused tests for adapters, extractors, graph utilities, registry behavior, and the CLI entry points.

12. **Packaging and deployment boundary**
   The project is packaged as both a Python distribution (`pyproject.toml`, `setup.py`, `requirements.txt`, `uv.lock`) and a Node package for the bridge (`bridge/package.json`, root `package.json`). The architecture therefore has two consumer surfaces: direct Python CLI/library use and indirect JS/TS invocation via the bridge.

Main entry points: [`codetraverse/base/component_extractor.py`](https://github.com/juspay/codetraverse/blob/main/codetraverse/base/component_extractor.py) (Component model), [`codetraverse/utils/networkx_graph.py`](https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/networkx_graph.py) (Graph build), [`tests`](https://github.com/juspay/codetraverse/tree/main/tests) (Tests), [`bridge/src/bridge.ts`](https://github.com/juspay/codetraverse/blob/main/bridge/src/bridge.ts) (Bridge API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_engine["Python engine"]
  node_root_main["CLI<br/>python entrypoint<br/>[main.py]"]
  node_pkg_main["Module CLI<br/>python module<br/>[main.py]"]
  node_path_cli["Path CLI<br/>python query<br/>[path.py]"]
  node_component_extractor["Component model<br/>core abstraction"]
  node_extractor_registry["Registry<br/>dispatcher"]
  node_networkx_graph["Graph build<br/>graph assembly<br/>[networkx_graph.py]"]
  node_graph_partitioner["Partitioning<br/>graph utility"]
  node_blackbox["Graph query<br/>query utility<br/>[blackbox.py]"]
  node_ast_orchestrator["Diff orchestration<br/>ast diff"]
  node_basefilediff["Base diff<br/>diff core<br/>[basefilediff.py]"]
end

subgraph group_language_support["Language support"]
  node_ts_extractor["TypeScript<br/>extractor"]
  node_py_extractor["Python<br/>extractor"]
  node_go_extractor["Go<br/>extractor<br/>[go_extractor.py]"]
  node_haskell_extractor["Haskell<br/>extractor"]
  node_rust_extractor["Rust<br/>extractor<br/>[rust_extractor.py]"]
  node_rescript_extractor["ReScript<br/>extractor"]
end

subgraph group_bridge["TS bridge"]
  node_ts_bridge["Bridge API<br/>node bridge<br/>[bridge.ts]"]
  node_python_runner["Python runner<br/>node subprocess<br/>[python-runner.ts]"]
  node_bridge_index["Bridge entry<br/>node entrypoint<br/>[index.ts]"]
end

subgraph group_validation["Validation"]
  node_sample_repo[("Sample repos<br/>fixtures")]
  node_tests_root["Tests<br/>test suite"]
end

subgraph group_packaging["Packaging"]
  node_py_package["Python package<br/>distribution<br/>[pyproject.toml]"]
  node_node_package["Node package<br/>distribution<br/>[package.json]"]
end

node_root_main -->|"delegates to"| node_pkg_main
node_pkg_main -->|"selects"| node_extractor_registry
node_extractor_registry -->|"implements"| node_component_extractor
node_component_extractor -->|"specializes"| node_ts_extractor
node_component_extractor -->|"specializes"| node_py_extractor
node_component_extractor -->|"specializes"| node_go_extractor
node_component_extractor -->|"specializes"| node_haskell_extractor
node_component_extractor -->|"specializes"| node_rust_extractor
node_component_extractor -->|"specializes"| node_rescript_extractor
node_ts_extractor -->|"feeds"| node_networkx_graph
node_py_extractor -->|"feeds"| node_networkx_graph
node_go_extractor -->|"feeds"| node_networkx_graph
node_haskell_extractor -->|"feeds"| node_networkx_graph
node_rust_extractor -->|"feeds"| node_networkx_graph
node_rescript_extractor -->|"feeds"| node_networkx_graph
node_networkx_graph -->|"organizes"| node_graph_partitioner
node_path_cli -->|"queries"| node_blackbox
node_ast_orchestrator -->|"uses"| node_basefilediff
node_ts_bridge -->|"invokes"| node_python_runner
node_bridge_index -->|"exports"| node_ts_bridge
node_sample_repo -.->|"validates"| node_tests_root
node_tests_root -.->|"covers"| node_component_extractor
node_tests_root -.->|"covers"| node_networkx_graph
node_py_package -->|"packages"| node_root_main
node_node_package -->|"packages"| node_ts_bridge

click node_root_main "https://github.com/juspay/codetraverse/blob/main/main.py"
click node_pkg_main "https://github.com/juspay/codetraverse/blob/main/codetraverse/main.py"
click node_path_cli "https://github.com/juspay/codetraverse/blob/main/codetraverse/path.py"
click node_component_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/base/component_extractor.py"
click node_extractor_registry "https://github.com/juspay/codetraverse/blob/main/codetraverse/registry/extractor_registry.py"
click node_networkx_graph "https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/networkx_graph.py"
click node_graph_partitioner "https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/graph_partitioner.py"
click node_blackbox "https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/blackbox.py"
click node_ast_orchestrator "https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/AstDifferOrchestrator.py"
click node_basefilediff "https://github.com/juspay/codetraverse/blob/main/codetraverse/ast_diff/basefilediff.py"
click node_ts_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/typescript_extractor.py"
click node_py_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/python_extractor.py"
click node_go_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/go_extractor.py"
click node_haskell_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/haskell_extractor.py"
click node_rust_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/rust_extractor.py"
click node_rescript_extractor "https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/rescript_extractor.py"
click node_ts_bridge "https://github.com/juspay/codetraverse/blob/main/bridge/src/bridge.ts"
click node_python_runner "https://github.com/juspay/codetraverse/blob/main/bridge/src/python-runner.ts"
click node_bridge_index "https://github.com/juspay/codetraverse/blob/main/bridge/src/index.ts"
click node_sample_repo "https://github.com/juspay/codetraverse/tree/main/sample_code_repo_test"
click node_tests_root "https://github.com/juspay/codetraverse/tree/main/tests"
click node_py_package "https://github.com/juspay/codetraverse/blob/main/pyproject.toml"
click node_node_package "https://github.com/juspay/codetraverse/blob/main/bridge/package.json"

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_root_main,node_pkg_main,node_path_cli,node_component_extractor,node_extractor_registry,node_networkx_graph,node_graph_partitioner,node_blackbox,node_ast_orchestrator,node_basefilediff toneBlue
class node_ts_extractor,node_py_extractor,node_go_extractor,node_haskell_extractor,node_rust_extractor,node_rescript_extractor toneAmber
class node_ts_bridge,node_python_runner,node_bridge_index toneMint
class node_sample_repo,node_tests_root toneRose
class node_py_package,node_node_package toneIndigo
```

## Components

### Python engine

Static analysis core, CLI entry points, graph construction, and diff workflows.

- [CLI](https://github.com/juspay/codetraverse/blob/main/main.py): python entrypoint · Top-level command for analyzing a repository. · `main.py`
- [Module CLI](https://github.com/juspay/codetraverse/blob/main/codetraverse/main.py): python module · Internal Python entry point behind the root script. · `codetraverse/main.py`
- [Path CLI](https://github.com/juspay/codetraverse/blob/main/codetraverse/path.py): python query · CLI for querying the generated dependency graph. · `codetraverse/path.py`
- [Component model](https://github.com/juspay/codetraverse/blob/main/codetraverse/base/component_extractor.py): core abstraction · Language-agnostic component extraction contract. · `codetraverse/base/component_extractor.py`
- [Registry](https://github.com/juspay/codetraverse/blob/main/codetraverse/registry/extractor_registry.py): dispatcher · Maps file types and languages to extractor implementations. · `codetraverse/registry/extractor_registry.py`
- [Graph build](https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/networkx_graph.py): graph assembly · Builds the repository-wide dependency graph using NetworkX. · `codetraverse/utils/networkx_graph.py`
- [Partitioning](https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/graph_partitioner.py): graph utility · Splits or organizes the constructed graph for downstream use. · `codetraverse/utils/graph_partitioner.py`
- [Graph query](https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/blackbox.py): query utility · Supports neighborhood and path-style queries over the graph. · `codetraverse/utils/blackbox.py`
- [Diff orchestration](https://github.com/juspay/codetraverse/blob/main/codetraverse/utils/AstDifferOrchestrator.py): ast diff · Coordinates AST-level comparison workflows across languages. · `codetraverse/utils/AstDifferOrchestrator.py`
- [Base diff](https://github.com/juspay/codetraverse/blob/main/codetraverse/ast_diff/basefilediff.py): diff core · Shared diff primitives used by language-specific change detectors. · `codetraverse/ast_diff/basefilediff.py`

### Language support

Per-language extractors and adapters that normalize source code into the shared model.

- [TypeScript](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/typescript_extractor.py): extractor · TypeScript structural extraction front end. · `codetraverse/extractors/typescript_extractor.py`
- [Python](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/python_extractor.py): extractor · Python structural extraction front end. · `codetraverse/extractors/python_extractor.py`
- [Go](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/go_extractor.py): extractor · Go structural extraction front end. · `codetraverse/extractors/go_extractor.py`
- [Haskell](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/haskell_extractor.py): extractor · Haskell structural extraction front end. · `codetraverse/extractors/haskell_extractor.py`
- [Rust](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/rust_extractor.py): extractor · Rust structural extraction front end. · `codetraverse/extractors/rust_extractor.py`
- [ReScript](https://github.com/juspay/codetraverse/blob/main/codetraverse/extractors/rescript_extractor.py): extractor · ReScript structural extraction front end. · `codetraverse/extractors/rescript_extractor.py`

### TS bridge

Node/TypeScript wrapper that launches the Python engine for JS consumers.

- [Bridge API](https://github.com/juspay/codetraverse/blob/main/bridge/src/bridge.ts): node bridge · TypeScript facade exposed to JavaScript consumers. · `bridge/src/bridge.ts`
- [Python runner](https://github.com/juspay/codetraverse/blob/main/bridge/src/python-runner.ts): node subprocess · Launches the Python analysis engine from Node. · `bridge/src/python-runner.ts`
- [Bridge entry](https://github.com/juspay/codetraverse/blob/main/bridge/src/index.ts): node entrypoint · Bridge package entry point and export surface. · `bridge/src/index.ts`

### Validation

Sample repositories and tests used to verify extraction, graphing, and CLI behavior.

- [Sample repos](https://github.com/juspay/codetraverse/tree/main/sample_code_repo_test): fixtures · Miniature language repositories used for extraction validation. · `sample_code_repo_test`
- [Tests](https://github.com/juspay/codetraverse/tree/main/tests): test suite · Repository-wide test suite covering extractors, adapters, graph utilities, and CLIs. · `tests`

### Packaging

Distribution and installation boundaries for Python and Node consumers.

- [Python package](https://github.com/juspay/codetraverse/blob/main/pyproject.toml): distribution · Python packaging and install metadata for the analysis engine. · `pyproject.toml`
- [Node package](https://github.com/juspay/codetraverse/blob/main/bridge/package.json): distribution · Node packaging metadata for the bridge. · `bridge/package.json`

## Connections

- CLI → Module CLI: delegates to · The root CLI routes into the package implementation.
- Module CLI → Registry: selects · Analysis starts by choosing an extractor for each source file.
- Registry → Component model: implements · Concrete extractors conform to the shared extraction contract.
- Component model → TypeScript: specializes · TypeScript analysis is one implementation of the common model.
- Component model → Python: specializes · Python analysis is one implementation of the common model.
- Component model → Go: specializes · Go analysis is one implementation of the common model.
- Component model → Haskell: specializes · Haskell analysis is one implementation of the common model.
- Component model → Rust: specializes · Rust analysis is one implementation of the common model.
- Component model → ReScript: specializes · ReScript analysis is one implementation of the common model.
- TypeScript → Graph build: feeds · Extracted components are assembled into the repo graph.
- Python → Graph build: feeds · Extracted components are assembled into the repo graph.
- Go → Graph build: feeds · Extracted components are assembled into the repo graph.
- Haskell → Graph build: feeds · Extracted components are assembled into the repo graph.
- Rust → Graph build: feeds · Extracted components are assembled into the repo graph.
- ReScript → Graph build: feeds · Extracted components are assembled into the repo graph.
- Graph build → Partitioning: organizes · Graph utilities can partition or reshape the dependency graph.
- Path CLI → Graph query: queries · Path-oriented queries use the graph query utility.
- Diff orchestration → Base diff: uses · Language-specific diff workflows share base diff logic.
- Bridge API → Python runner: invokes · The bridge launches Python analysis as a subprocess.
- Bridge entry → Bridge API: exports · Package entry points surface the bridge API.
- Sample repos → Tests: validates · Fixture repositories support cross-language behavior checks.
- Tests → Component model: covers · Tests exercise the extraction abstraction and implementations.
- Tests → Graph build: covers · Tests exercise graph assembly and related utilities.
- Python package → CLI: packages · Python packaging exposes the CLI and library entry points.
- Node package → Bridge API: packages · Node packaging exposes the bridge for JS/TS consumers.
