# maxpoww/waveview architecture

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

- Interactive diagram: https://gitdiagram.com/maxpoww/waveview
- Repository: https://github.com/maxpoww/waveview

## Overview

This is a Hyprland plugin whose C++ runtime combines a multi-workspace overview, a per-workspace window spread, stage/zoom transitions, and floating-window titlebars with window actions. The main workflow is compositor window/workspace state → capture and layout → interactive overview or spread → workspace/window changes and recapture. Rust supplies pure layout logic through a C ABI; the titlebar subsystem draws through Hyprland’s render pass. The README is empty, and the sampled main.cpp is partial, so uncertain event wiring and unsampled capability links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/maxpoww/waveview/blob/main/src/main.cpp) (Plugin Runtime), [`src/hyprbars/golemBar.cpp`](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/golemBar.cpp) (Titlebar Decoration), [`src/hyprbars/bars.cpp`](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/bars.cpp) (Bar Lifecycle), [`src/hyprbars/BarPassElement.cpp`](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/BarPassElement.cpp) (Render Pass Element)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_overview["Overview and Capture"]
  node_plugin["Plugin Runtime<br/>[main.cpp]"]
  node_capture["Workspace Capture<br/>[main.cpp]"]
  node_overview_ui["Overview Interaction<br/>[main.cpp]"]
  node_spread_ui["Workspace Spread<br/>[main.cpp]"]
  node_stage["Stage and Zoom<br/>[main.cpp]"]
  node_dock["Minimize Dock<br/>[main.cpp]"]
end

subgraph group_layout["Layout Logic"]
  node_rust_layout["Layout and Hit Testing<br/>[lib.rs]"]
end

subgraph group_bars["Window Bars"]
  node_bars_setup["Bar Lifecycle<br/>[bars.cpp]"]
  node_bar_decoration["Titlebar Decoration<br/>[golemBar.cpp]"]
  node_bar_state["Bar Actions and State<br/>[barsGlobals.hpp]"]
  node_bar_pass["Render Pass Element<br/>[BarPassElement.cpp]"]
end

subgraph group_integration["Compositor and Daemon"]
  node_hyprland["Hyprland Compositor"]
  node_waverunner["Waverunner Daemon"]
end

node_user(("Desktop User"))

node_user -->|"uses desktop"| node_hyprland
node_hyprland -->|"provides runtime state"| node_plugin
node_plugin -->|"captures workspaces"| node_capture
node_capture -->|"reads windows and renders"| node_hyprland
node_plugin -->|"calls layout logic"| node_rust_layout
node_plugin -->|"handles overview input"| node_overview_ui
node_plugin -->|"handles spread input"| node_spread_ui
node_plugin -->|"controls transitions"| node_stage
node_plugin -->|"handles minimize and restore"| node_dock
node_overview_ui -->|"changes focus and workspace"| node_hyprland
node_spread_ui -->|"moves windows"| node_hyprland
node_dock -->|"parks minimized windows"| node_hyprland
node_plugin -->|"initializes bars"| node_bars_setup
node_bars_setup -->|"attaches decorations"| node_bar_decoration
node_bar_decoration -->|"queues drawing"| node_bar_pass
node_bar_pass -->|"renders decoration"| node_bar_decoration
node_bar_decoration -->|"reads button state"| node_bar_state
node_bar_decoration -->|"sends action messages"| node_plugin
node_plugin -->|"sends socket messages"| node_waverunner
node_waverunner -.->|"supplies daemon commands"| node_plugin

click node_plugin "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_capture "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_overview_ui "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_spread_ui "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_stage "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_dock "https://github.com/maxpoww/waveview/blob/main/src/main.cpp"
click node_rust_layout "https://github.com/maxpoww/waveview/blob/main/rust/src/lib.rs"
click node_bars_setup "https://github.com/maxpoww/waveview/blob/main/src/hyprbars/bars.cpp"
click node_bar_decoration "https://github.com/maxpoww/waveview/blob/main/src/hyprbars/golemBar.cpp"
click node_bar_state "https://github.com/maxpoww/waveview/blob/main/src/hyprbars/barsGlobals.hpp"
click node_bar_pass "https://github.com/maxpoww/waveview/blob/main/src/hyprbars/BarPassElement.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_plugin,node_capture,node_overview_ui,node_spread_ui,node_stage,node_dock,node_user toneBlue
class node_rust_layout toneAmber
class node_bars_setup,node_bar_decoration,node_bar_state,node_bar_pass toneMint
class node_hyprland,node_waverunner toneRose
```

## Components

### Overview and Capture

- [Plugin Runtime](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`
- [Workspace Capture](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`
- [Overview Interaction](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`
- [Workspace Spread](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`
- [Stage and Zoom](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`
- [Minimize Dock](https://github.com/maxpoww/waveview/blob/main/src/main.cpp): `src/main.cpp`

### Layout Logic

- [Layout and Hit Testing](https://github.com/maxpoww/waveview/blob/main/rust/src/lib.rs): `rust/src/lib.rs`

### Window Bars

- [Bar Lifecycle](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/bars.cpp): `src/hyprbars/bars.cpp`
- [Titlebar Decoration](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/golemBar.cpp): `src/hyprbars/golemBar.cpp`
- [Bar Actions and State](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/barsGlobals.hpp): `src/hyprbars/barsGlobals.hpp`
- [Render Pass Element](https://github.com/maxpoww/waveview/blob/main/src/hyprbars/BarPassElement.cpp): `src/hyprbars/BarPassElement.cpp`

### Compositor and Daemon

- **Hyprland Compositor**
- **Waverunner Daemon**

### Other components

- **Desktop User**

## Connections

- Desktop User → Hyprland Compositor: uses desktop
- Hyprland Compositor → Plugin Runtime: provides runtime state
- Plugin Runtime → Workspace Capture: captures workspaces
- Workspace Capture → Hyprland Compositor: reads windows and renders
- Plugin Runtime → Layout and Hit Testing: calls layout logic
- Plugin Runtime → Overview Interaction: handles overview input
- Plugin Runtime → Workspace Spread: handles spread input
- Plugin Runtime → Stage and Zoom: controls transitions
- Plugin Runtime → Minimize Dock: handles minimize and restore
- Overview Interaction → Hyprland Compositor: changes focus and workspace
- Workspace Spread → Hyprland Compositor: moves windows
- Minimize Dock → Hyprland Compositor: parks minimized windows
- Plugin Runtime → Bar Lifecycle: initializes bars
- Bar Lifecycle → Titlebar Decoration: attaches decorations
- Titlebar Decoration → Render Pass Element: queues drawing
- Render Pass Element → Titlebar Decoration: renders decoration
- Titlebar Decoration → Bar Actions and State: reads button state
- Titlebar Decoration → Plugin Runtime: sends action messages
- Plugin Runtime → Waverunner Daemon: sends socket messages
- Waverunner Daemon → Plugin Runtime: supplies daemon commands