# justskiv/goschedviz architecture

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

- Interactive diagram: https://gitdiagram.com/justskiv/goschedviz
- Repository: https://github.com/justskiv/goschedviz

## Overview

goschedviz is a terminal dashboard for observing a Go program’s runtime scheduler. The CLI starts a target with GODEBUG schedtrace, collects and parses scheduler output, retains recent snapshots, converts them into UI data, and updates the terminal display. A target can optionally use the metrics reporter to emit goroutine counts. The graph follows relationships shown in the excerpts and README; individual widget implementations are linked through the renderer, while unsampled collector details are not inferred.

Main entry points: [`internal/ui/termui/renderer.go`](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/renderer.go) (Terminal renderer), [`cmd/goschedviz/main.go`](https://github.com/justskiv/goschedviz/blob/main/cmd/goschedviz/main.go) (Monitor CLI), [`internal/collector/godebug/collector.go`](https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/collector.go) (GODEBUG collector), [`internal/collector/godebug/parser.go`](https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/parser.go) (Trace parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Monitoring runtime"]
  node_cli["Monitor CLI<br/>[main.go]"]
  node_collector["GODEBUG collector<br/>[collector.go]"]
end

subgraph group_data["Metrics and state"]
  node_parser["Trace parser<br/>[parser.go]"]
  node_snapshot["Scheduler snapshots<br/>[scheduler.go]"]
  node_state["Monitor history<br/>[scheduler.go]"]
end

subgraph group_display["Terminal presentation"]
  node_ui_data["UI data model<br/>[dto.go]"]
  node_presenter["Presenter contract<br/>[presenter.go]"]
  node_renderer["Terminal renderer<br/>[renderer.go]"]
  node_table["Current values table<br/>[table.go]"]
  node_bars["Local queue bars<br/>[barchart.go]"]
  node_gauges["Metric gauges<br/>[gauge.go]"]
  node_plots["History plots<br/>[plots.go]"]
  node_legend["Plot legend<br/>[legend.go]"]
  node_info["Info panel<br/>[info.go]"]
end

subgraph group_integration["Target integration"]
  node_target["Go target process"]
  node_reporter["Goroutine reporter<br/>[metrics.go]"]
end

node_user(("CLI user"))

node_user -->|"starts"| node_cli
node_cli -->|"starts collection"| node_collector
node_collector -->|"launches with schedtrace"| node_target
node_target -->|"writes stderr"| node_collector
node_collector -->|"parses output with"| node_parser
node_parser -->|"produces"| node_snapshot
node_collector -->|"sends snapshots"| node_cli
node_cli -->|"updates"| node_state
node_state -->|"returns latest and history"| node_cli
node_cli -->|"converts snapshots"| node_ui_data
node_cli -->|"updates"| node_presenter
node_reporter -.->|"exports goroutine count"| node_target
node_parser -->|"adds parsed goroutine count"| node_snapshot
node_renderer -->|"implements"| node_presenter
node_renderer -->|"updates and renders"| node_table
node_renderer -->|"updates and renders"| node_bars
node_renderer -->|"updates and renders"| node_gauges
node_renderer -->|"updates and renders"| node_plots
node_renderer -->|"renders"| node_legend
node_renderer -->|"updates and renders"| node_info

click node_cli "https://github.com/justskiv/goschedviz/blob/main/cmd/goschedviz/main.go"
click node_collector "https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/collector.go"
click node_parser "https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/parser.go"
click node_snapshot "https://github.com/justskiv/goschedviz/blob/main/internal/domain/scheduler.go"
click node_state "https://github.com/justskiv/goschedviz/blob/main/internal/domain/scheduler.go"
click node_reporter "https://github.com/justskiv/goschedviz/blob/main/pkg/metrics/metrics.go"
click node_ui_data "https://github.com/justskiv/goschedviz/blob/main/internal/ui/dto.go"
click node_presenter "https://github.com/justskiv/goschedviz/blob/main/internal/ui/presenter.go"
click node_renderer "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/renderer.go"
click node_table "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/table.go"
click node_bars "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/barchart.go"
click node_gauges "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/gauge.go"
click node_plots "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/plots.go"
click node_legend "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/legend.go"
click node_info "https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/info.go"

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_user toneBlue
class node_parser,node_snapshot,node_state toneAmber
class node_ui_data,node_presenter,node_renderer,node_table,node_bars,node_gauges,node_plots,node_legend,node_info toneMint
class node_target,node_reporter toneRose
```

## Components

### Monitoring runtime

- [Monitor CLI](https://github.com/justskiv/goschedviz/blob/main/cmd/goschedviz/main.go): `cmd/goschedviz/main.go`
- [GODEBUG collector](https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/collector.go): `internal/collector/godebug/collector.go`

### Metrics and state

- [Trace parser](https://github.com/justskiv/goschedviz/blob/main/internal/collector/godebug/parser.go): `internal/collector/godebug/parser.go`
- [Scheduler snapshots](https://github.com/justskiv/goschedviz/blob/main/internal/domain/scheduler.go): `internal/domain/scheduler.go`
- [Monitor history](https://github.com/justskiv/goschedviz/blob/main/internal/domain/scheduler.go): `internal/domain/scheduler.go`

### Terminal presentation

- [UI data model](https://github.com/justskiv/goschedviz/blob/main/internal/ui/dto.go): `internal/ui/dto.go`
- [Presenter contract](https://github.com/justskiv/goschedviz/blob/main/internal/ui/presenter.go): `internal/ui/presenter.go`
- [Terminal renderer](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/renderer.go): `internal/ui/termui/renderer.go`
- [Current values table](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/table.go): `internal/ui/termui/widgets/table.go`
- [Local queue bars](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/barchart.go): `internal/ui/termui/widgets/barchart.go`
- [Metric gauges](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/gauge.go): `internal/ui/termui/widgets/gauge.go`
- [History plots](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/plots.go): `internal/ui/termui/widgets/plots.go`
- [Plot legend](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/legend.go): `internal/ui/termui/widgets/legend.go`
- [Info panel](https://github.com/justskiv/goschedviz/blob/main/internal/ui/termui/widgets/info.go): `internal/ui/termui/widgets/info.go`

### Target integration

- **Go target process**
- [Goroutine reporter](https://github.com/justskiv/goschedviz/blob/main/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`

### Other components

- **CLI user**

## Connections

- CLI user → Monitor CLI: starts (evidence: `README.md`)
- Monitor CLI → GODEBUG collector: starts collection (evidence: `cmd/goschedviz/main.go`)
- GODEBUG collector → Go target process: launches with schedtrace (evidence: `internal/collector/godebug/collector.go`)
- Go target process → GODEBUG collector: writes stderr (evidence: `internal/collector/godebug/collector.go`)
- GODEBUG collector → Trace parser: parses output with (evidence: `internal/collector/godebug/collector.go`)
- Trace parser → Scheduler snapshots: produces (evidence: `internal/collector/godebug/parser.go`)
- GODEBUG collector → Monitor CLI: sends snapshots (evidence: `cmd/goschedviz/main.go`)
- Monitor CLI → Monitor history: updates (evidence: `cmd/goschedviz/main.go`)
- Monitor history → Monitor CLI: returns latest and history (evidence: `cmd/goschedviz/main.go`)
- Monitor CLI → UI data model: converts snapshots (evidence: `cmd/goschedviz/main.go`)
- Monitor CLI → Presenter contract: updates (evidence: `cmd/goschedviz/main.go`)
- Goroutine reporter → Go target process: exports goroutine count (evidence: `README.md`)
- Trace parser → Scheduler snapshots: adds parsed goroutine count (evidence: `internal/collector/godebug/parser.go`)
- Terminal renderer → Presenter contract: implements (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → Current values table: updates and renders (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → Local queue bars: updates and renders (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → Metric gauges: updates and renders (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → History plots: updates and renders (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → Plot legend: renders (evidence: `internal/ui/termui/renderer.go`)
- Terminal renderer → Info panel: updates and renders (evidence: `internal/ui/termui/renderer.go`)
