# mehrdat/nd36-code-visualizer architecture

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

- Interactive diagram: https://gitdiagram.com/mehrdat/nd36-code-visualizer
- Repository: https://github.com/mehrdat/nd36-code-visualizer

## Overview

ND36 is a recording debugger: a user runs a Python or C/C++ program, ND36 records an event trace, and the user explores or shares that run through CLI views, a live UI, or a standalone report. The Python and Rust implementations share a trace schema; Rust provides a recorder and reader/explorer, while the documented analysis surface includes execution graphs, memory, DataFrame lineage, tensor diagnostics, and Perfetto export. Some capability paths are documented but their implementation was not sampled, so those components are shown without speculative internal wiring.

Main entry points: [`nd36/cli.py`](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/cli.py) (Python CLI), [`nd36/report.py`](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/report.py) (Static report), [`ndr/src/main.rs`](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/main.rs) (Rust CLI), [`nd36/server.py`](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/server.py) (Live UI server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_pycli["Python CLI<br/>[cli.py]"]
  node_rustcli["Rust CLI<br/>[main.rs]"]
end

subgraph group_record["Recording and traces"]
  node_pyrecord["Python recorder<br/>[recorder.py]"]
  node_native["Native debugger runner<br/>[native.py]"]
  node_rustrecord["Rust recorder<br/>[recorder.rs]"]
  node_encode["Value encoder<br/>[encode.rs]"]
  node_schema["Trace schema<br/>[schema.py]"]
  node_rustschema["Rust trace schema<br/>[schema.rs]"]
  node_pystore[("Python trace store<br/>[store.py]")]
  node_rustwriter[("Rust trace writer<br/>[writer.rs]")]
end

subgraph group_inspect["Trace inspection"]
  node_reader["Rust trace reader<br/>[reader.rs]"]
  node_ruststore["Explorer state store<br/>[store.rs]"]
  node_explorer["Rust run explorer<br/>[mod.rs]"]
  node_pyexplorer["Python run explorer<br/>[explore.py]"]
end

subgraph group_views["User interfaces"]
  node_server["Live UI server<br/>[server.py]"]
  node_report["Static report<br/>[report.py]"]
  node_app["Desktop shell<br/>[app.py]"]
  node_vscode["VS Code panel<br/>[extension.js]"]
end

subgraph group_insights["Run analysis"]
  node_graphs["Call and flow graphs<br/>[graphs.py]"]
  node_memory["Memory analysis<br/>[memory.py]"]
  node_lineage["DataFrame lineage<br/>[lineage.py]"]
  node_domains["Tensor domains<br/>[domains.py]"]
  node_charts["Timeline charts<br/>[charts.py]"]
  node_exporter["Perfetto export<br/>[exporter.py]"]
end

node_user(("Developer"))

node_user -->|"runs and explores"| node_pycli
node_pycli -->|"dispatches native runs"| node_native
node_pycli -->|"dispatches exploration"| node_pyexplorer
node_pycli -->|"dispatches reports"| node_report
node_pycli -->|"starts live UI"| node_server
node_pycli -->|"opens app shell"| node_app
node_pycli -->|"dispatches flow views"| node_graphs
node_pycli -->|"dispatches memory views"| node_memory
node_pycli -->|"dispatches data views"| node_lineage
node_pycli -->|"dispatches export"| node_exporter
node_pycli -->|"runs native programs"| node_native
node_native -->|"writes compatible trace"| node_schema
node_pyrecord -->|"emits schema events"| node_schema
node_rustcli -->|"runs recorder"| node_rustrecord
node_rustrecord -->|"encodes values"| node_encode
node_rustrecord -->|"records events"| node_rustschema
node_rustcli -->|"writes run trace"| node_rustwriter
node_rustwriter -->|"packs trace records"| node_rustschema
node_rustcli -->|"opens trace"| node_reader
node_reader -->|"provides trace data"| node_ruststore
node_ruststore -->|"rebuilds run state"| node_explorer
node_rustcli -->|"dispatches exploration"| node_explorer
node_pycli -->|"reads trace data"| node_pystore
node_server -->|"serves trace state"| node_pystore
node_report -->|"renders graphs"| node_graphs
node_report -->|"renders timelines"| node_charts
node_report -->|"renders memory panel"| node_memory
node_report -->|"renders lineage panel"| node_lineage
node_server -->|"serves graph panels"| node_graphs
node_server -->|"serves data panels"| node_lineage
node_vscode -->|"starts same server"| node_server
node_user -->|"runs Rust commands"| node_rustcli
node_user -->|"records Python run"| node_pyrecord
node_user -->|"views tensor shapes"| node_domains
node_user -->|"inspects timelines"| node_charts

click node_pycli "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/cli.py"
click node_rustcli "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/main.rs"
click node_pyrecord "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/recorder.py"
click node_native "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/native.py"
click node_rustrecord "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/recorder.rs"
click node_encode "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/encode.rs"
click node_schema "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/schema.py"
click node_rustschema "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/schema.rs"
click node_pystore "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/store.py"
click node_rustwriter "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/writer.rs"
click node_reader "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/reader.rs"
click node_ruststore "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/explore/store.rs"
click node_explorer "https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/explore/mod.rs"
click node_pyexplorer "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/explore.py"
click node_server "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/server.py"
click node_report "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/report.py"
click node_app "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/app.py"
click node_vscode "https://github.com/mehrdat/nd36-code-visualizer/blob/main/vscode-extension/extension.js"
click node_graphs "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/graphs.py"
click node_memory "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/memory.py"
click node_lineage "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/lineage.py"
click node_domains "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/domains.py"
click node_charts "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/charts.py"
click node_exporter "https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/exporter.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_pycli,node_rustcli toneBlue
class node_pyrecord,node_native,node_rustrecord,node_encode,node_schema,node_rustschema,node_pystore,node_rustwriter toneAmber
class node_reader,node_ruststore,node_explorer,node_pyexplorer toneMint
class node_server,node_report,node_app,node_vscode toneRose
class node_graphs,node_memory,node_lineage,node_domains,node_charts,node_exporter,node_user toneIndigo
```

## Components

### Entry points

- [Python CLI](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/cli.py): `nd36/cli.py`
- [Rust CLI](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/main.rs): `ndr/src/main.rs`

### Recording and traces

- [Python recorder](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/recorder.py): `nd36/recorder.py`
- [Native debugger runner](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/native.py): `nd36/native.py`
- [Rust recorder](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/recorder.rs): `ndr/src/recorder.rs`
- [Value encoder](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/encode.rs): `ndr/src/encode.rs`
- [Trace schema](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/schema.py): `nd36/schema.py`
- [Rust trace schema](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/schema.rs): `ndr/src/schema.rs`
- [Python trace store](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/store.py): `nd36/store.py`
- [Rust trace writer](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/writer.rs): `ndr/src/writer.rs`

### Trace inspection

- [Rust trace reader](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/reader.rs): `ndr/src/reader.rs`
- [Explorer state store](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/explore/store.rs): `ndr/src/explore/store.rs`
- [Rust run explorer](https://github.com/mehrdat/nd36-code-visualizer/blob/main/ndr/src/explore/mod.rs): `ndr/src/explore/mod.rs`
- [Python run explorer](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/explore.py): `nd36/explore.py`

### User interfaces

- [Live UI server](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/server.py): `nd36/server.py`
- [Static report](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/report.py): `nd36/report.py`
- [Desktop shell](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/app.py): `nd36/app.py`
- [VS Code panel](https://github.com/mehrdat/nd36-code-visualizer/blob/main/vscode-extension/extension.js): `vscode-extension/extension.js`

### Run analysis

- [Call and flow graphs](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/graphs.py): `nd36/graphs.py`
- [Memory analysis](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/memory.py): `nd36/memory.py`
- [DataFrame lineage](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/lineage.py): `nd36/lineage.py`
- [Tensor domains](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/domains.py): `nd36/domains.py`
- [Timeline charts](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/charts.py): `nd36/charts.py`
- [Perfetto export](https://github.com/mehrdat/nd36-code-visualizer/blob/main/nd36/exporter.py): `nd36/exporter.py`

### Other components

- **Developer**

## Connections

- Developer → Python CLI: runs and explores (evidence: `README.md`)
- Python CLI → Native debugger runner: dispatches native runs (evidence: `nd36/cli.py`)
- Python CLI → Python run explorer: dispatches exploration (evidence: `nd36/cli.py`)
- Python CLI → Static report: dispatches reports (evidence: `nd36/cli.py`)
- Python CLI → Live UI server: starts live UI (evidence: `nd36/cli.py`)
- Python CLI → Desktop shell: opens app shell (evidence: `nd36/cli.py`)
- Python CLI → Call and flow graphs: dispatches flow views (evidence: `nd36/cli.py`)
- Python CLI → Memory analysis: dispatches memory views (evidence: `nd36/cli.py`)
- Python CLI → DataFrame lineage: dispatches data views (evidence: `nd36/cli.py`)
- Python CLI → Perfetto export: dispatches export (evidence: `nd36/cli.py`)
- Python CLI → Native debugger runner: runs native programs (evidence: `README.md`)
- Native debugger runner → Trace schema: writes compatible trace (evidence: `README.md`)
- Python recorder → Trace schema: emits schema events (evidence: `nd36/recorder.py`)
- Rust CLI → Rust recorder: runs recorder (evidence: `ndr/src/main.rs`)
- Rust recorder → Value encoder: encodes values (evidence: `ndr/src/recorder.rs`)
- Rust recorder → Rust trace schema: records events (evidence: `ndr/src/recorder.rs`)
- Rust CLI → Rust trace writer: writes run trace (evidence: `ndr/src/main.rs`)
- Rust trace writer → Rust trace schema: packs trace records (evidence: `ndr/src/writer.rs`)
- Rust CLI → Rust trace reader: opens trace (evidence: `ndr/src/main.rs`)
- Rust trace reader → Explorer state store: provides trace data (evidence: `ndr/src/explore/store.rs`)
- Explorer state store → Rust run explorer: rebuilds run state (evidence: `ndr/src/explore/store.rs`)
- Rust CLI → Rust run explorer: dispatches exploration (evidence: `ndr/src/main.rs`)
- Python CLI → Python trace store: reads trace data (evidence: `nd36/cli.py`)
- Live UI server → Python trace store: serves trace state (evidence: `nd36/server.py`)
- Static report → Call and flow graphs: renders graphs (evidence: `nd36/report.py`)
- Static report → Timeline charts: renders timelines (evidence: `nd36/report.py`)
- Static report → Memory analysis: renders memory panel (evidence: `nd36/report.py`)
- Static report → DataFrame lineage: renders lineage panel (evidence: `nd36/report.py`)
- Live UI server → Call and flow graphs: serves graph panels (evidence: `nd36/server.py`)
- Live UI server → DataFrame lineage: serves data panels (evidence: `nd36/server.py`)
- VS Code panel → Live UI server: starts same server (evidence: `README.md`)
- Developer → Rust CLI: runs Rust commands (evidence: `README.md`)
- Developer → Python recorder: records Python run (evidence: `README.md`)
- Developer → Tensor domains: views tensor shapes (evidence: `README.md`)
- Developer → Timeline charts: inspects timelines (evidence: `README.md`)