# 1catai/1cat-linkstat architecture

> Architecture diagram of the GitHub repository 1catai/1cat-linkstat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1catai/1cat-linkstat
- Repository: https://github.com/1catai/1cat-linkstat

## Overview

1CatLinkStat is a Linux/NVIDIA terminal GPU and NVLink monitor, with a separate CUDA peer-to-peer bandwidth benchmark. The primary workflow is CLI options → repeated or one-shot snapshot collection → optional change tracking → terminal or JSON output. Collection combines NVML device/process data with optional live NVLink metrics, topology, and host process details; snapshots are the shared data contract. The README also documents summary, expanded-link, and topology-matrix views. The benchmark’s runtime orchestration is described in the README, but its Python implementation was not sampled.

Main entry points: [`src/cat_linkstat/nvml.py`](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py) (Snapshot Collector), [`src/cat_linkstat/cli.py`](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/cli.py) (Monitor CLI), [`src/cat_linkstat/render.py`](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/render.py) (Terminal Renderer), [`src/cat_linkstat/bench.py`](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/bench.py) (Benchmark CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_monitor["Monitoring"]
  node_cli["Monitor CLI<br/>[cli.py]"]
  node_collector["Snapshot Collector<br/>[nvml.py]"]
  node_nvml["NVML Access<br/>[nvml.py]"]
  node_dcgm["DCGM Sampler<br/>[nvml.py]"]
  node_gpm["NVLink Sampler<br/>[nvml.py]"]
  node_topology["Topology Sampler<br/>[nvml.py]"]
  node_processes["Process Sampler<br/>[nvml.py]"]
  node_snapshot["Snapshot Models<br/>[models.py]"]
  node_tracker["Change Tracker<br/>[tracking.py]"]
end

subgraph group_presentation["Presentation"]
  node_renderer["Terminal Renderer<br/>[render.py]"]
  node_history["Activity History<br/>[render.py]"]
end

subgraph group_benchmark["Bandwidth Benchmark"]
  node_benchcli["Benchmark CLI<br/>[bench.py]"]
  node_cudabench["CUDA Benchmark"]
end

subgraph group_external["External Interfaces"]
  node_gpu{{"NVIDIA GPUs"}}
  node_nvmllib["NVML Library"]
  node_dcgmservice["DCGM Tools"]
  node_nvsmi["nvidia-smi"]
  node_hosttools["Host Process Tools"]
  node_cuda["CUDA Toolkit"]
  node_terminal(("Terminal"))
end

node_user(("Operator"))

node_user -->|"sets options"| node_cli
node_cli -->|"collects snapshot"| node_collector
node_collector -->|"reads device data"| node_nvml
node_nvml -->|"calls"| node_nvmllib
node_nvmllib -->|"queries"| node_gpu
node_collector -->|"samples totals"| node_dcgm
node_dcgm -.->|"queries metrics"| node_dcgmservice
node_collector -->|"samples NVLink"| node_gpm
node_gpm -->|"probes metrics"| node_nvsmi
node_collector -->|"samples topology"| node_topology
node_topology -->|"reads topology"| node_nvsmi
node_collector -->|"samples processes"| node_processes
node_processes -->|"reads GPU processes"| node_nvsmi
node_processes -->|"reads process details"| node_hosttools
node_collector -->|"builds snapshots"| node_snapshot
node_cli -->|"tracks changes"| node_tracker
node_tracker -->|"compares snapshots"| node_snapshot
node_cli -->|"renders views"| node_renderer
node_renderer -->|"reads snapshot"| node_snapshot
node_renderer -->|"updates trends"| node_history
node_cli -->|"serializes JSON"| node_snapshot
node_renderer -->|"writes display"| node_terminal
node_cli -->|"writes output"| node_terminal
node_user -->|"starts benchmark"| node_benchcli
node_benchcli -->|"checks and invokes nvcc"| node_cuda
node_benchcli -->|"builds and runs"| node_cudabench
node_cudabench -->|"tests peer bandwidth"| node_gpu
node_benchcli -->|"reports results"| node_terminal

click node_cli "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/cli.py"
click node_collector "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_nvml "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_dcgm "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_gpm "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_topology "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_processes "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py"
click node_snapshot "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/models.py"
click node_tracker "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/tracking.py"
click node_renderer "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/render.py"
click node_history "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/render.py"
click node_benchcli "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/bench.py"
click node_cudabench "https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvlink_microbench.cu"

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_collector,node_nvml,node_dcgm,node_gpm,node_topology,node_processes,node_snapshot,node_tracker toneBlue
class node_renderer,node_history toneAmber
class node_benchcli,node_cudabench toneMint
class node_gpu,node_nvmllib,node_dcgmservice,node_nvsmi,node_hosttools,node_cuda,node_terminal toneRose
class node_user toneIndigo
```

## Components

### Monitoring

- [Monitor CLI](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/cli.py): `src/cat_linkstat/cli.py`
- [Snapshot Collector](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [NVML Access](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [DCGM Sampler](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [NVLink Sampler](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [Topology Sampler](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [Process Sampler](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvml.py): `src/cat_linkstat/nvml.py`
- [Snapshot Models](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/models.py): `src/cat_linkstat/models.py`
- [Change Tracker](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/tracking.py): `src/cat_linkstat/tracking.py`

### Presentation

- [Terminal Renderer](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/render.py): `src/cat_linkstat/render.py`
- [Activity History](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/render.py): `src/cat_linkstat/render.py`

### Bandwidth Benchmark

- [Benchmark CLI](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/bench.py): `src/cat_linkstat/bench.py`
- [CUDA Benchmark](https://github.com/1catai/1cat-linkstat/blob/main/src/cat_linkstat/nvlink_microbench.cu): `src/cat_linkstat/nvlink_microbench.cu`

### External Interfaces

- **NVIDIA GPUs**
- **NVML Library**
- **DCGM Tools**
- **nvidia-smi**
- **Host Process Tools**
- **CUDA Toolkit**
- **Terminal**

### Other components

- **Operator**

## Connections

- Operator → Monitor CLI: sets options
- Monitor CLI → Snapshot Collector: collects snapshot
- Snapshot Collector → NVML Access: reads device data
- NVML Access → NVML Library: calls
- NVML Library → NVIDIA GPUs: queries
- Snapshot Collector → DCGM Sampler: samples totals
- DCGM Sampler → DCGM Tools: queries metrics
- Snapshot Collector → NVLink Sampler: samples NVLink
- NVLink Sampler → nvidia-smi: probes metrics
- Snapshot Collector → Topology Sampler: samples topology
- Topology Sampler → nvidia-smi: reads topology
- Snapshot Collector → Process Sampler: samples processes
- Process Sampler → nvidia-smi: reads GPU processes
- Process Sampler → Host Process Tools: reads process details
- Snapshot Collector → Snapshot Models: builds snapshots
- Monitor CLI → Change Tracker: tracks changes
- Change Tracker → Snapshot Models: compares snapshots
- Monitor CLI → Terminal Renderer: renders views
- Terminal Renderer → Snapshot Models: reads snapshot
- Terminal Renderer → Activity History: updates trends
- Monitor CLI → Snapshot Models: serializes JSON
- Terminal Renderer → Terminal: writes display
- Monitor CLI → Terminal: writes output
- Operator → Benchmark CLI: starts benchmark
- Benchmark CLI → CUDA Toolkit: checks and invokes nvcc
- Benchmark CLI → CUDA Benchmark: builds and runs
- CUDA Benchmark → NVIDIA GPUs: tests peer bandwidth
- Benchmark CLI → Terminal: reports results