# pliablerigidity/llmvis architecture

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

- Interactive diagram: https://gitdiagram.com/pliablerigidity/llmvis
- Repository: https://github.com/pliablerigidity/llmvis

## Overview

LLMVis visualizes local LLM inference in observer mode (Ollama) or deep-instrumentation mode (PyTorch/MLX), with a terminal UI for live telemetry and model execution details. The main flow is backend events through normalized events and shared state into the appropriate TUI; deep mode also accepts prompts over TCP, while recording and replay provide a separate session workflow. README documents the six deep-mode views and platform-specific telemetry. Some subsystem links rely on README or SOURCE INDEX references because their implementation was not excerpted.

Main entry points: [`src/llmvis/cli/main.py`](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/cli/main.py) (CLI commands), [`src/llmvis/tui/app.py`](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app.py) (Observer application), [`src/llmvis/tui/app_deep.py`](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app_deep.py) (Deep application), [`src/llmvis/core/events.py`](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/events.py) (Normalized events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands and sessions"]
  node_cli["CLI commands<br/>[main.py]"]
  node_recording["Session recording<br/>[replay_adapter.py]"]
end

subgraph group_backends["Inference backends"]
  node_replay["Replay adapter<br/>[replay_adapter.py]"]
  node_transformers["PyTorch instrumentation"]
  node_mlx["MLX instrumentation<br/>[mlx_adapter.py]"]
  node_ollama_adapter["Ollama observer<br/>[ollama.py]"]
  node_server["Telemetry TCP server<br/>[server.py]"]
  node_client["TCP client adapter<br/>[client_adapter.py]"]
end

subgraph group_runtime["Events and state"]
  node_events["Normalized events<br/>[events.py]"]
  node_bus["Event bus<br/>[bus.py]"]
  node_state["Shared app state<br/>[state.py]"]
end

subgraph group_visualization["Terminal visualization"]
  node_observer_app["Observer application<br/>[app.py]"]
  node_deep_app["Deep application<br/>[app_deep.py]"]
  node_views["Screens and widgets"]
  node_education["Concept explanations<br/>[concepts.py]"]
end

subgraph group_telemetry["Platform telemetry"]
  node_platform["Platform detection<br/>[detect.py]"]
  node_system_telemetry["System telemetry<br/>[system.py]"]
  node_gpu_telemetry["NVIDIA telemetry<br/>[gpu.py]"]
  node_provider["Telemetry providers"]
  node_snapshot["Hardware snapshot<br/>[snapshot.py]"]
end

node_user(("Operator"))
node_ollama["Ollama service"]

node_user -->|"runs commands"| node_cli
node_cli -->|"starts instrumentation"| node_transformers
node_cli -->|"selects backend"| node_mlx
node_cli -->|"starts server"| node_server
node_cli -->|"starts replay"| node_replay
node_cli -->|"opens deep TUI"| node_deep_app
node_cli -->|"opens observer TUI"| node_observer_app
node_cli -->|"selects observer"| node_ollama_adapter
node_ollama -->|"serves HTTP data"| node_ollama_adapter
node_transformers -->|"emits events"| node_events
node_mlx -->|"emits events"| node_events
node_ollama_adapter -->|"emits events"| node_events
node_replay -->|"reconstructs events"| node_events
node_transformers -->|"publishes telemetry"| node_server
node_server -->|"streams JSONL"| node_client
node_client -->|"yields events"| node_events
node_client -->|"sends prompts"| node_server
node_server -->|"dispatches prompts"| node_transformers
node_events -->|"queued for dispatch"| node_bus
node_deep_app -->|"publishes events"| node_bus
node_observer_app -->|"dispatches events"| node_bus
node_deep_app -->|"updates state"| node_state
node_observer_app -->|"updates state"| node_state
node_deep_app -->|"renders views"| node_views
node_observer_app -->|"renders screen"| node_views
node_views -->|"reads state"| node_state
node_views -->|"shows concepts"| node_education
node_cli -->|"detects platform"| node_platform
node_observer_app -->|"collects system stats"| node_system_telemetry
node_observer_app -->|"collects GPU stats"| node_gpu_telemetry
node_deep_app -->|"collects system stats"| node_system_telemetry
node_deep_app -->|"collects GPU stats"| node_gpu_telemetry
node_provider -->|"returns snapshot"| node_snapshot
node_provider -->|"returns snapshot"| node_snapshot
node_provider -->|"returns snapshot"| node_snapshot

click node_cli "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/cli/main.py"
click node_recording "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/replay_adapter.py"
click node_replay "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/replay_adapter.py"
click node_transformers "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/instrumented_transformers.py"
click node_mlx "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/mlx_adapter.py"
click node_ollama_adapter "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/ollama.py"
click node_server "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/ipc/server.py"
click node_client "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/client_adapter.py"
click node_events "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/events.py"
click node_bus "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/bus.py"
click node_state "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/state.py"
click node_observer_app "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app.py"
click node_deep_app "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app_deep.py"
click node_views "https://github.com/pliablerigidity/llmvis/tree/main/src/llmvis/tui/screens"
click node_education "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/educational/concepts.py"
click node_platform "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/platform/detect.py"
click node_system_telemetry "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/system.py"
click node_gpu_telemetry "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/gpu.py"
click node_provider "https://github.com/pliablerigidity/llmvis/tree/main/src/llmvis/telemetry/providers"
click node_snapshot "https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/snapshot.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_cli,node_recording toneBlue
class node_replay,node_transformers,node_mlx,node_ollama_adapter,node_server,node_client toneAmber
class node_events,node_bus,node_state toneMint
class node_observer_app,node_deep_app,node_views,node_education toneRose
class node_platform,node_system_telemetry,node_gpu_telemetry,node_provider,node_snapshot,node_user,node_ollama toneIndigo
```

## Components

### Commands and sessions

- [CLI commands](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/cli/main.py): `src/llmvis/cli/main.py`
- [Session recording](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/replay_adapter.py): `src/llmvis/adapters/replay_adapter.py`

### Inference backends

- [Replay adapter](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/replay_adapter.py): `src/llmvis/adapters/replay_adapter.py`
- [PyTorch instrumentation](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/instrumented_transformers.py): `src/llmvis/adapters/instrumented_transformers.py`
- [MLX instrumentation](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/mlx_adapter.py): `src/llmvis/adapters/mlx_adapter.py`
- [Ollama observer](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/ollama.py): `src/llmvis/adapters/ollama.py`
- [Telemetry TCP server](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/ipc/server.py): `src/llmvis/ipc/server.py`
- [TCP client adapter](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/adapters/client_adapter.py): `src/llmvis/adapters/client_adapter.py`

### Events and state

- [Normalized events](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/events.py): `src/llmvis/core/events.py`
- [Event bus](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/bus.py): `src/llmvis/core/bus.py`
- [Shared app state](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/core/state.py): `src/llmvis/core/state.py`

### Terminal visualization

- [Observer application](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app.py): `src/llmvis/tui/app.py`
- [Deep application](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/tui/app_deep.py): `src/llmvis/tui/app_deep.py`
- [Screens and widgets](https://github.com/pliablerigidity/llmvis/tree/main/src/llmvis/tui/screens): `src/llmvis/tui/screens`
- [Concept explanations](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/educational/concepts.py): `src/llmvis/educational/concepts.py`

### Platform telemetry

- [Platform detection](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/platform/detect.py): `src/llmvis/platform/detect.py`
- [System telemetry](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/system.py): `src/llmvis/telemetry/system.py`
- [NVIDIA telemetry](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/gpu.py): `src/llmvis/telemetry/gpu.py`
- [Telemetry providers](https://github.com/pliablerigidity/llmvis/tree/main/src/llmvis/telemetry/providers): `src/llmvis/telemetry/providers`
- [Hardware snapshot](https://github.com/pliablerigidity/llmvis/blob/main/src/llmvis/telemetry/snapshot.py): `src/llmvis/telemetry/snapshot.py`

### Other components

- **Operator**
- **Ollama service**

## Connections

- Operator → CLI commands: runs commands
- CLI commands → PyTorch instrumentation: starts instrumentation (evidence: `src/llmvis/cli/main.py`)
- CLI commands → MLX instrumentation: selects backend (evidence: `src/llmvis/cli/main.py`)
- CLI commands → Telemetry TCP server: starts server (evidence: `src/llmvis/cli/main.py`)
- CLI commands → Replay adapter: starts replay (evidence: `src/llmvis/cli/main.py`)
- CLI commands → Deep application: opens deep TUI (evidence: `src/llmvis/cli/main.py`)
- CLI commands → Observer application: opens observer TUI (evidence: `src/llmvis/cli/main.py`)
- CLI commands → Ollama observer: selects observer
- Ollama service → Ollama observer: serves HTTP data
- PyTorch instrumentation → Normalized events: emits events (evidence: `src/llmvis/adapters/instrumented_transformers.py`)
- MLX instrumentation → Normalized events: emits events (evidence: `src/llmvis/adapters/mlx_adapter.py`)
- Ollama observer → Normalized events: emits events (evidence: `src/llmvis/adapters/ollama.py`)
- Replay adapter → Normalized events: reconstructs events (evidence: `src/llmvis/adapters/replay_adapter.py`)
- PyTorch instrumentation → Telemetry TCP server: publishes telemetry
- Telemetry TCP server → TCP client adapter: streams JSONL
- TCP client adapter → Normalized events: yields events (evidence: `src/llmvis/adapters/client_adapter.py`)
- TCP client adapter → Telemetry TCP server: sends prompts (evidence: `src/llmvis/adapters/client_adapter.py`)
- Telemetry TCP server → PyTorch instrumentation: dispatches prompts (evidence: `src/llmvis/ipc/server.py`)
- Normalized events → Event bus: queued for dispatch (evidence: `src/llmvis/core/bus.py`)
- Deep application → Event bus: publishes events (evidence: `src/llmvis/tui/app_deep.py`)
- Observer application → Event bus: dispatches events (evidence: `src/llmvis/tui/app.py`)
- Deep application → Shared app state: updates state (evidence: `src/llmvis/tui/app_deep.py`)
- Observer application → Shared app state: updates state (evidence: `src/llmvis/tui/app.py`)
- Deep application → Screens and widgets: renders views (evidence: `src/llmvis/tui/app_deep.py`)
- Observer application → Screens and widgets: renders screen (evidence: `src/llmvis/tui/app.py`)
- Screens and widgets → Shared app state: reads state (evidence: `src/llmvis/tui/screens/main_screen.py`)
- Screens and widgets → Concept explanations: shows concepts (evidence: `src/llmvis/tui/screens/concept_screen.py`)
- CLI commands → Platform detection: detects platform (evidence: `src/llmvis/cli/main.py`)
- Observer application → System telemetry: collects system stats (evidence: `src/llmvis/tui/app.py`)
- Observer application → NVIDIA telemetry: collects GPU stats (evidence: `src/llmvis/tui/app.py`)
- Deep application → System telemetry: collects system stats (evidence: `src/llmvis/tui/app_deep.py`)
- Deep application → NVIDIA telemetry: collects GPU stats (evidence: `src/llmvis/tui/app_deep.py`)
- Telemetry providers → Hardware snapshot: returns snapshot (evidence: `src/llmvis/telemetry/providers/apple.py`)
- Telemetry providers → Hardware snapshot: returns snapshot (evidence: `src/llmvis/telemetry/providers/nvidia.py`)
- Telemetry providers → Hardware snapshot: returns snapshot (evidence: `src/llmvis/telemetry/providers/system.py`)
