# sam0uly/bubblemonitor architecture

> Architecture diagram of the GitHub repository sam0uly/bubblemonitor, 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/sam0uly/bubblemonitor
- Repository: https://github.com/sam0uly/bubblemonitor

## Overview

bubbleMonitor is a terminal system monitor: users launch the BubbleTea interface, which periodically requests system and process data, stores it in application state, and renders it in interactive tabs and overlays. Its documented capabilities also include remote SSH monitoring, health analysis, alerts, and snapshot export; their exact runtime wiring is not fully visible in the sampled excerpts. The graph includes those subsystems at supported paths, but omits uncertain links. Evidence is limited to the README and the supplied excerpts and source index.

Main entry points: [`internal/app/model.go`](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/model.go) (App model), [`internal/provider/adapters.go`](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/adapters.go) (Provider adapters), [`internal/data/groups.go`](https://github.com/sam0uly/bubblemonitor/blob/master/internal/data/groups.go) (Monitor state), [`internal/app/update.go`](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/update.go) (Event update)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_tui["Interactive TUI<br/>[main.go]"]
  node_cli["CLI commands<br/>[root.go]"]
end

subgraph group_app["Application flow"]
  node_model["App model<br/>[model.go]"]
  node_update["Event update<br/>[update.go]"]
  node_keyboard["Keyboard handling<br/>[keyboard.go]"]
end

subgraph group_providers["Data providers"]
  node_adapters["Provider adapters<br/>[adapters.go]"]
  node_system["System metrics<br/>[hardware.go]"]
  node_services["Service discovery<br/>[services.go]"]
  node_processes["Process operations<br/>[list.go]"]
  node_remote["SSH monitoring<br/>[ssh.go]"]
  node_systemextras["System capabilities"]
end

subgraph group_state["State and analysis"]
  node_state["Monitor state<br/>[groups.go]"]
  node_messages["Async messages<br/>[messages.go]"]
  node_alerts["Threshold alerts<br/>[alerts.go]"]
  node_analysis["Health analysis<br/>[analysis.go]"]
  node_snapshot["Snapshot export<br/>[export.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_presentation["Terminal interface"]
  node_layout["TUI layout<br/>[layout.go]"]
  node_tabs["Monitor tabs<br/>[system.go]"]
  node_overlays["Help and settings<br/>[help.go]"]
  node_charts["Metric charts<br/>[charts.go]"]
end

node_user(("Terminal user"))

node_user -->|"launches"| node_tui
node_user -->|"runs commands"| node_cli
node_tui -->|"creates"| node_model
node_model -->|"initializes"| node_adapters
node_model -->|"initializes"| node_state
node_model -->|"loads"| node_config
node_model -->|"uses"| node_layout
node_update -->|"dispatches"| node_keyboard
node_update -->|"requests metrics"| node_adapters
node_update -->|"updates"| node_state
node_update -->|"handles"| node_messages
node_keyboard -->|"saves settings"| node_config
node_keyboard -->|"requests files"| node_processes
node_adapters -->|"delegates"| node_system
node_adapters -->|"delegates"| node_processes
node_adapters -->|"delegates"| node_remote
node_system -.->|"returns metrics"| node_messages
node_services -->|"returns services"| node_messages
node_services -->|"uses service types"| node_state
node_remote -->|"returns remote data"| node_messages
node_remote -->|"populates metrics"| node_state
node_layout -->|"renders"| node_tabs
node_layout -->|"renders"| node_overlays
node_layout -->|"uses"| node_charts
node_tabs -->|"reads"| node_state
node_tabs -.->|"uses"| node_charts
node_user -.->|"configures SSH"| node_remote
node_user -.->|"sets thresholds"| node_alerts
node_user -.->|"views health score"| node_analysis
node_user -.->|"exports snapshot"| node_snapshot
node_systemextras -.->|"reports system data"| node_user

click node_tui "https://github.com/sam0uly/bubblemonitor/blob/master/cmd/bub/main.go"
click node_cli "https://github.com/sam0uly/bubblemonitor/blob/master/cmd/bub/root.go"
click node_model "https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/model.go"
click node_update "https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/update.go"
click node_keyboard "https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/handlers/keyboard.go"
click node_adapters "https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/adapters.go"
click node_system "https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/system/hardware.go"
click node_services "https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/system/services.go"
click node_processes "https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/process/list.go"
click node_remote "https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/remote/ssh.go"
click node_systemextras "https://github.com/sam0uly/bubblemonitor/tree/master/internal/provider/system"
click node_state "https://github.com/sam0uly/bubblemonitor/blob/master/internal/data/groups.go"
click node_messages "https://github.com/sam0uly/bubblemonitor/blob/master/internal/msg/messages.go"
click node_alerts "https://github.com/sam0uly/bubblemonitor/blob/master/internal/data/alerts.go"
click node_analysis "https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/analysis.go"
click node_snapshot "https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/export.go"
click node_layout "https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/layout.go"
click node_tabs "https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/tabs/system.go"
click node_overlays "https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/overlays/help.go"
click node_charts "https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/widgets/charts.go"
click node_config "https://github.com/sam0uly/bubblemonitor/blob/master/internal/config/config.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_tui,node_cli,node_user toneBlue
class node_model,node_update,node_keyboard toneAmber
class node_adapters,node_system,node_services,node_processes,node_remote,node_systemextras toneMint
class node_state,node_messages,node_alerts,node_analysis,node_snapshot,node_config toneRose
class node_layout,node_tabs,node_overlays,node_charts toneIndigo
```

## Components

### Entry points

- [Interactive TUI](https://github.com/sam0uly/bubblemonitor/blob/master/cmd/bub/main.go): `cmd/bub/main.go`
- [CLI commands](https://github.com/sam0uly/bubblemonitor/blob/master/cmd/bub/root.go): `cmd/bub/root.go`

### Application flow

- [App model](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/model.go): `internal/app/model.go`
- [Event update](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/update.go): `internal/app/update.go`
- [Keyboard handling](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/handlers/keyboard.go): `internal/app/handlers/keyboard.go`

### Data providers

- [Provider adapters](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/adapters.go): `internal/provider/adapters.go`
- [System metrics](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/system/hardware.go): `internal/provider/system/hardware.go`
- [Service discovery](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/system/services.go): `internal/provider/system/services.go`
- [Process operations](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/process/list.go): `internal/provider/process/list.go`
- [SSH monitoring](https://github.com/sam0uly/bubblemonitor/blob/master/internal/provider/remote/ssh.go): `internal/provider/remote/ssh.go`
- [System capabilities](https://github.com/sam0uly/bubblemonitor/tree/master/internal/provider/system): `internal/provider/system`

### State and analysis

- [Monitor state](https://github.com/sam0uly/bubblemonitor/blob/master/internal/data/groups.go): `internal/data/groups.go`
- [Async messages](https://github.com/sam0uly/bubblemonitor/blob/master/internal/msg/messages.go): `internal/msg/messages.go`
- [Threshold alerts](https://github.com/sam0uly/bubblemonitor/blob/master/internal/data/alerts.go): `internal/data/alerts.go`
- [Health analysis](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/analysis.go): `internal/app/analysis.go`
- [Snapshot export](https://github.com/sam0uly/bubblemonitor/blob/master/internal/app/export.go): `internal/app/export.go`
- [Configuration](https://github.com/sam0uly/bubblemonitor/blob/master/internal/config/config.go): `internal/config/config.go`

### Terminal interface

- [TUI layout](https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/layout.go): `internal/ui/layout.go`
- [Monitor tabs](https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/tabs/system.go): `internal/ui/tabs/system.go`
- [Help and settings](https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/overlays/help.go): `internal/ui/overlays/help.go`
- [Metric charts](https://github.com/sam0uly/bubblemonitor/blob/master/internal/ui/widgets/charts.go): `internal/ui/widgets/charts.go`

### Other components

- **Terminal user**

## Connections

- Terminal user → Interactive TUI: launches
- Terminal user → CLI commands: runs commands
- Interactive TUI → App model: creates (evidence: `cmd/bub/main.go`)
- App model → Provider adapters: initializes (evidence: `internal/app/model.go`)
- App model → Monitor state: initializes (evidence: `internal/app/model.go`)
- App model → Configuration: loads (evidence: `internal/app/model.go`)
- App model → TUI layout: uses (evidence: `internal/app/model.go`)
- Event update → Keyboard handling: dispatches (evidence: `internal/app/update.go`)
- Event update → Provider adapters: requests metrics (evidence: `internal/app/update.go`)
- Event update → Monitor state: updates (evidence: `internal/app/update.go`)
- Event update → Async messages: handles (evidence: `internal/app/update.go`)
- Keyboard handling → Configuration: saves settings (evidence: `internal/app/handlers/keyboard.go`)
- Keyboard handling → Process operations: requests files (evidence: `internal/app/handlers/keyboard.go`)
- Provider adapters → System metrics: delegates (evidence: `internal/provider/adapters.go`)
- Provider adapters → Process operations: delegates (evidence: `internal/provider/adapters.go`)
- Provider adapters → SSH monitoring: delegates (evidence: `internal/provider/adapters.go`)
- System metrics → Async messages: returns metrics
- Service discovery → Async messages: returns services (evidence: `internal/provider/system/services.go`)
- Service discovery → Monitor state: uses service types (evidence: `internal/provider/system/services.go`)
- SSH monitoring → Async messages: returns remote data (evidence: `internal/provider/remote/ssh.go`)
- SSH monitoring → Monitor state: populates metrics (evidence: `internal/provider/remote/ssh.go`)
- TUI layout → Monitor tabs: renders (evidence: `internal/ui/layout.go`)
- TUI layout → Help and settings: renders (evidence: `internal/ui/layout.go`)
- TUI layout → Metric charts: uses (evidence: `internal/ui/layout.go`)
- Monitor tabs → Monitor state: reads
- Monitor tabs → Metric charts: uses
- Terminal user → SSH monitoring: configures SSH
- Terminal user → Threshold alerts: sets thresholds
- Terminal user → Health analysis: views health score
- Terminal user → Snapshot export: exports snapshot
- System capabilities → Terminal user: reports system data
