# mahendra-go/local-llm-instrumentation-tracing-and-replay-platform architecture

> Architecture diagram of the GitHub repository mahendra-go/local-llm-instrumentation-tracing-and-replay-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform
- Repository: https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform

## Overview

llmtrace observes transformer inference events, then supports live dashboarding or recording and replay. The principal workflow is selecting a synthetic, replay, or llama.cpp source in the CLI; events are captured or loaded, then streamed into the dashboard or written to a trace. Session aggregation supports topology, metrics, attention, and anomaly views. The README documents the dashboard capabilities and capture callback; some internal dashboard wiring is not shown in the excerpts, so those links are limited to documented relationships.

Main entry points: [`src/main.cpp`](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/main.cpp) (CLI dispatcher), [`src/dashboard.cpp`](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp) (Interactive dashboard), [`src/capture/llama_capture.cpp`](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/capture/llama_capture.cpp) (Llama capture), [`src/session.cpp`](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/session.cpp) (Session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_cli["CLI dispatcher<br/>[main.cpp]"]
end

subgraph group_sources["Event sources"]
  node_synthetic["Synthetic generator<br/>[source.cpp]"]
  node_replay["Replay stream<br/>[source.cpp]"]
  node_capture["Llama capture<br/>[llama_capture.cpp]"]
end

subgraph group_runtime["Event state"]
  node_event["Layer events<br/>[event.cpp]"]
  node_ring["Bounded buffers<br/>[ring_buffer.hpp]"]
  node_topology["Topology builder<br/>[topology.cpp]"]
  node_session["Session state<br/>[session.cpp]"]
end

subgraph group_traces["Trace storage"]
  node_traceio["Trace reader/writer<br/>[trace_io.cpp]"]
  node_tracefile["Trace file"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Interactive dashboard<br/>[dashboard.cpp]"]
  node_topopanel["Topology panel<br/>[dashboard.cpp]"]
  node_eventpanel["Event stream<br/>[dashboard.cpp]"]
  node_metricpanels["Metrics and alerts<br/>[dashboard.cpp]"]
end

node_user(("Engineer"))
node_llama["llama.cpp"]

node_user -->|"selects mode"| node_cli
node_cli -->|"constructs source"| node_synthetic
node_cli -->|"constructs source"| node_replay
node_cli -->|"starts capture"| node_capture
node_capture -->|"registers callback"| node_llama
node_capture -->|"emits events"| node_event
node_synthetic -->|"generates events"| node_event
node_replay -->|"replays events"| node_event
node_cli -->|"loads trace"| node_traceio
node_cli -->|"writes trace"| node_traceio
node_traceio -->|"reads and writes"| node_tracefile
node_cli -->|"runs dashboard"| node_dashboard
node_dashboard -->|"aggregates stream"| node_session
node_session -->|"retains events"| node_ring
node_session -->|"observes events"| node_topology
node_dashboard -->|"renders topology"| node_topopanel
node_dashboard -->|"renders events"| node_eventpanel
node_dashboard -->|"renders diagnostics"| node_metricpanels

click node_cli "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/main.cpp"
click node_synthetic "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/source.cpp"
click node_replay "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/source.cpp"
click node_capture "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/capture/llama_capture.cpp"
click node_event "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/event.cpp"
click node_ring "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/include/llmtrace/ring_buffer.hpp"
click node_topology "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/topology.cpp"
click node_session "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/session.cpp"
click node_traceio "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/trace_io.cpp"
click node_dashboard "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp"
click node_topopanel "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp"
click node_eventpanel "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp"
click node_metricpanels "https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp"

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 toneBlue
class node_synthetic,node_replay,node_capture toneAmber
class node_event,node_ring,node_topology,node_session toneMint
class node_traceio,node_tracefile toneRose
class node_dashboard,node_topopanel,node_eventpanel,node_metricpanels,node_user,node_llama toneIndigo
```

## Components

### CLI workflow

- [CLI dispatcher](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/main.cpp): `src/main.cpp`

### Event sources

- [Synthetic generator](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/source.cpp): `src/source.cpp`
- [Replay stream](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/source.cpp): `src/source.cpp`
- [Llama capture](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/capture/llama_capture.cpp): `src/capture/llama_capture.cpp`

### Event state

- [Layer events](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/event.cpp): `src/event.cpp`
- [Bounded buffers](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/include/llmtrace/ring_buffer.hpp): `include/llmtrace/ring_buffer.hpp`
- [Topology builder](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/topology.cpp): `src/topology.cpp`
- [Session state](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/session.cpp): `src/session.cpp`

### Trace storage

- [Trace reader/writer](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/trace_io.cpp): `src/trace_io.cpp`
- **Trace file**

### Dashboard

- [Interactive dashboard](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp): `src/dashboard.cpp`
- [Topology panel](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp): `src/dashboard.cpp`
- [Event stream](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp): `src/dashboard.cpp`
- [Metrics and alerts](https://github.com/mahendra-go/local-llm-instrumentation-tracing-and-replay-platform/blob/main/src/dashboard.cpp): `src/dashboard.cpp`

### Other components

- **Engineer**
- **llama.cpp**

## Connections

- Engineer → CLI dispatcher: selects mode (evidence: `src/main.cpp`)
- CLI dispatcher → Synthetic generator: constructs source (evidence: `src/main.cpp`)
- CLI dispatcher → Replay stream: constructs source (evidence: `src/main.cpp`)
- CLI dispatcher → Llama capture: starts capture (evidence: `src/main.cpp`)
- Llama capture → llama.cpp: registers callback (evidence: `README.md`)
- Llama capture → Layer events: emits events (evidence: `src/capture/llama_capture.cpp`)
- Synthetic generator → Layer events: generates events
- Replay stream → Layer events: replays events
- CLI dispatcher → Trace reader/writer: loads trace (evidence: `src/main.cpp`)
- CLI dispatcher → Trace reader/writer: writes trace (evidence: `src/main.cpp`)
- Trace reader/writer → Trace file: reads and writes
- CLI dispatcher → Interactive dashboard: runs dashboard (evidence: `src/main.cpp`)
- Interactive dashboard → Session state: aggregates stream (evidence: `README.md`)
- Session state → Bounded buffers: retains events (evidence: `src/session.cpp`)
- Session state → Topology builder: observes events (evidence: `src/session.cpp`)
- Interactive dashboard → Topology panel: renders topology (evidence: `README.md`)
- Interactive dashboard → Event stream: renders events (evidence: `README.md`)
- Interactive dashboard → Metrics and alerts: renders diagnostics (evidence: `README.md`)
