# sqshq/sampler architecture

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

- Interactive diagram: https://gitdiagram.com/sqshq/sampler
- Repository: https://github.com/sqshq/sampler

## Overview

Sampler is a terminal application for running configured shell commands at intervals and visualizing their output. The principal workflow is YAML configuration → configured samplers and display components → sampled command output → terminal rendering; users can also interactively rearrange components and save changed positions. Distinct display stages include run charts, sparklines, bar charts, gauges, textboxes, and ASCII art. Conditional triggers provide alert and action capabilities. The architecture follows the visible startup and event-handling code; several links to unsampled internals are documented by the README rather than verified from implementation excerpts.

Main entry points: [`main.go`](https://github.com/sqshq/sampler/blob/master/main.go) (Application startup), [`component/layout/layout.go`](https://github.com/sqshq/sampler/blob/master/component/layout/layout.go) (Component layout), [`data/consumer.go`](https://github.com/sqshq/sampler/blob/master/data/consumer.go) (Sample consumers), [`data/sampler.go`](https://github.com/sqshq/sampler/blob/master/data/sampler.go) (Sampling scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_main["Application startup<br/>[main.go]"]
  node_config["YAML configuration<br/>[config.go]"]
end

subgraph group_sampling["Sampling and actions"]
  node_sampler["Sampling scheduler<br/>[sampler.go]"]
  node_consumer["Sample consumers<br/>[consumer.go]"]
  node_triggers["Conditional triggers<br/>[trigger.go]"]
end

subgraph group_display["Terminal visualization"]
  node_runchart["Run chart<br/>[runchart.go]"]
  node_sparkline["Sparkline<br/>[sparkline.go]"]
  node_barchart["Bar chart<br/>[barchart.go]"]
  node_gauge["Gauge<br/>[gauge.go]"]
  node_textbox["Textbox<br/>[textbox.go]"]
  node_asciibox["ASCII box<br/>[asciibox.go]"]
  node_layout["Component layout<br/>[layout.go]"]
end

subgraph group_runtime["Terminal runtime"]
  node_events["Event handler<br/>[handler.go]"]
  node_console["Terminal interface<br/>[console.go]"]
  node_audio["Audio player<br/>[player.go]"]
end

node_user(("User"))
node_shell["Shell commands"]

node_user -->|"starts"| node_main
node_main -->|"loads"| node_config
node_main -->|"starts samplers"| node_sampler
node_main -->|"creates triggers"| node_triggers
node_main -->|"creates"| node_runchart
node_main -->|"creates"| node_sparkline
node_main -->|"creates"| node_barchart
node_main -->|"creates"| node_gauge
node_main -->|"creates"| node_textbox
node_main -->|"creates"| node_asciibox
node_main -->|"builds"| node_layout
node_main -->|"starts handling"| node_events
node_main -->|"initializes"| node_console
node_main -->|"creates player"| node_audio
node_sampler -->|"executes commands"| node_shell
node_shell -->|"returns output"| node_sampler
node_sampler -.->|"delivers samples"| node_consumer
node_consumer -.->|"feeds samples"| node_runchart
node_consumer -.->|"feeds samples"| node_sparkline
node_consumer -.->|"feeds samples"| node_barchart
node_consumer -.->|"feeds samples"| node_gauge
node_consumer -.->|"feeds samples"| node_textbox
node_consumer -.->|"feeds samples"| node_asciibox
node_triggers -->|"plays alerts"| node_audio
node_triggers -->|"runs action script"| node_shell
node_triggers -->|"sends visual alerts"| node_consumer
node_events -->|"renders and routes input"| node_layout
node_events -->|"pauses samplers"| node_sampler
node_layout -.->|"handles terminal input"| node_console
node_events -->|"saves positions"| node_config
node_layout -->|"sends selection commands"| node_runchart
node_layout -.->|"renders components"| node_sparkline
node_layout -.->|"renders components"| node_barchart
node_layout -.->|"renders components"| node_gauge
node_layout -.->|"renders components"| node_textbox
node_layout -.->|"renders components"| node_asciibox

click node_main "https://github.com/sqshq/sampler/blob/master/main.go"
click node_config "https://github.com/sqshq/sampler/blob/master/config/config.go"
click node_sampler "https://github.com/sqshq/sampler/blob/master/data/sampler.go"
click node_consumer "https://github.com/sqshq/sampler/blob/master/data/consumer.go"
click node_triggers "https://github.com/sqshq/sampler/blob/master/data/trigger.go"
click node_runchart "https://github.com/sqshq/sampler/blob/master/component/runchart/runchart.go"
click node_sparkline "https://github.com/sqshq/sampler/blob/master/component/sparkline/sparkline.go"
click node_barchart "https://github.com/sqshq/sampler/blob/master/component/barchart/barchart.go"
click node_gauge "https://github.com/sqshq/sampler/blob/master/component/gauge/gauge.go"
click node_textbox "https://github.com/sqshq/sampler/blob/master/component/textbox/textbox.go"
click node_asciibox "https://github.com/sqshq/sampler/blob/master/component/asciibox/asciibox.go"
click node_layout "https://github.com/sqshq/sampler/blob/master/component/layout/layout.go"
click node_events "https://github.com/sqshq/sampler/blob/master/event/handler.go"
click node_console "https://github.com/sqshq/sampler/blob/master/console/console.go"
click node_audio "https://github.com/sqshq/sampler/blob/master/asset/player.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_main,node_config,node_user toneBlue
class node_sampler,node_consumer,node_triggers toneAmber
class node_runchart,node_sparkline,node_barchart,node_gauge,node_textbox,node_asciibox,node_layout toneMint
class node_events,node_console,node_audio toneRose
class node_shell toneIndigo
```

## Components

### Startup and configuration

- [Application startup](https://github.com/sqshq/sampler/blob/master/main.go): `main.go`
- [YAML configuration](https://github.com/sqshq/sampler/blob/master/config/config.go): `config/config.go`

### Sampling and actions

- [Sampling scheduler](https://github.com/sqshq/sampler/blob/master/data/sampler.go): `data/sampler.go`
- [Sample consumers](https://github.com/sqshq/sampler/blob/master/data/consumer.go): `data/consumer.go`
- [Conditional triggers](https://github.com/sqshq/sampler/blob/master/data/trigger.go): `data/trigger.go`

### Terminal visualization

- [Run chart](https://github.com/sqshq/sampler/blob/master/component/runchart/runchart.go): `component/runchart/runchart.go`
- [Sparkline](https://github.com/sqshq/sampler/blob/master/component/sparkline/sparkline.go): `component/sparkline/sparkline.go`
- [Bar chart](https://github.com/sqshq/sampler/blob/master/component/barchart/barchart.go): `component/barchart/barchart.go`
- [Gauge](https://github.com/sqshq/sampler/blob/master/component/gauge/gauge.go): `component/gauge/gauge.go`
- [Textbox](https://github.com/sqshq/sampler/blob/master/component/textbox/textbox.go): `component/textbox/textbox.go`
- [ASCII box](https://github.com/sqshq/sampler/blob/master/component/asciibox/asciibox.go): `component/asciibox/asciibox.go`
- [Component layout](https://github.com/sqshq/sampler/blob/master/component/layout/layout.go): `component/layout/layout.go`

### Terminal runtime

- [Event handler](https://github.com/sqshq/sampler/blob/master/event/handler.go): `event/handler.go`
- [Terminal interface](https://github.com/sqshq/sampler/blob/master/console/console.go): `console/console.go`
- [Audio player](https://github.com/sqshq/sampler/blob/master/asset/player.go): `asset/player.go`

### Other components

- **User**
- **Shell commands**

## Connections

- User → Application startup: starts
- Application startup → YAML configuration: loads (evidence: `main.go`)
- Application startup → Sampling scheduler: starts samplers (evidence: `main.go`)
- Application startup → Conditional triggers: creates triggers (evidence: `main.go`)
- Application startup → Run chart: creates (evidence: `main.go`)
- Application startup → Sparkline: creates (evidence: `main.go`)
- Application startup → Bar chart: creates (evidence: `main.go`)
- Application startup → Gauge: creates (evidence: `main.go`)
- Application startup → Textbox: creates (evidence: `main.go`)
- Application startup → ASCII box: creates (evidence: `main.go`)
- Application startup → Component layout: builds (evidence: `main.go`)
- Application startup → Event handler: starts handling (evidence: `main.go`)
- Application startup → Terminal interface: initializes (evidence: `main.go`)
- Application startup → Audio player: creates player (evidence: `main.go`)
- Sampling scheduler → Shell commands: executes commands
- Shell commands → Sampling scheduler: returns output
- Sampling scheduler → Sample consumers: delivers samples
- Sample consumers → Run chart: feeds samples
- Sample consumers → Sparkline: feeds samples
- Sample consumers → Bar chart: feeds samples
- Sample consumers → Gauge: feeds samples
- Sample consumers → Textbox: feeds samples
- Sample consumers → ASCII box: feeds samples
- Conditional triggers → Audio player: plays alerts (evidence: `data/trigger.go`)
- Conditional triggers → Shell commands: runs action script (evidence: `data/trigger.go`)
- Conditional triggers → Sample consumers: sends visual alerts (evidence: `data/trigger.go`)
- Event handler → Component layout: renders and routes input (evidence: `event/handler.go`)
- Event handler → Sampling scheduler: pauses samplers (evidence: `event/handler.go`)
- Component layout → Terminal interface: handles terminal input
- Event handler → YAML configuration: saves positions (evidence: `event/handler.go`)
- Component layout → Run chart: sends selection commands (evidence: `component/layout/layout.go`)
- Component layout → Sparkline: renders components
- Component layout → Bar chart: renders components
- Component layout → Gauge: renders components
- Component layout → Textbox: renders components
- Component layout → ASCII box: renders components
