# maxpoww/launcher architecture

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

## Overview

Waverunner is a persistent Wayland dock and launcher: a user reveals or opens the dock, searches its app grid, then launches an app or acts on an Install/Files result. The daemon owns the UI event loop and coordinates discovery, filtering, rendering, and actions; the CLI is a separate control path over a Unix socket. The graph preserves the README’s intellihide, pinning, package install, and file-search capabilities. Several daemon links are based on documented behavior because the supplied daemon excerpts are partial.

Main entry points: [`crates/daemon/src/main.rs`](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/main.rs) (Dock daemon), [`crates/client/src/main.rs`](https://github.com/maxpoww/launcher/blob/main/crates/client/src/main.rs) (Control CLI), [`crates/daemon/src/install.rs`](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/install.rs) (Package management), [`crates/daemon/src/renderer.rs`](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/renderer.rs) (Dock surface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and UI"]
  node_ctl["Control CLI<br/>[main.rs]"]
  node_protocol["Command protocol<br/>[lib.rs]"]
  node_daemon["Dock daemon<br/>[main.rs]"]
  node_surface["Dock surface<br/>[renderer.rs]"]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_discovery["Discovery and search"]
  node_appscan["App discovery<br/>[apps.rs]"]
  node_search["Fuzzy search<br/>[search.rs]"]
  node_appindex["App index<br/>[index.rs]"]
  node_files["File search<br/>[files.rs]"]
end

subgraph group_actions["Launch and management"]
  node_launch["App launch<br/>[launch.rs]"]
  node_install["Package management<br/>[install.rs]"]
  node_pins["Dock pins<br/>[pins.rs]"]
  node_groups["App groups<br/>[groups.rs]"]
  node_persistence["Saved state<br/>[persist.rs]"]
end

subgraph group_desktop["Desktop integration"]
  node_wayland["Wayland compositor"]
  node_hyprland["Hyprland"]
  node_nixpkgs[("Nix package catalog")]
  node_profile["Nix profile"]
end

node_user(("User"))

node_user -->|"sends commands"| node_ctl
node_ctl -->|"parses command"| node_protocol
node_ctl -->|"sends socket command"| node_daemon
node_daemon -->|"decodes command"| node_protocol
node_user -->|"uses dock"| node_surface
node_surface -->|"sends input"| node_daemon
node_daemon -->|"updates display"| node_surface
node_daemon -->|"creates surface"| node_wayland
node_daemon -->|"loads settings"| node_config
node_daemon -->|"requests rescan"| node_appscan
node_appscan -->|"builds index"| node_appindex
node_daemon -->|"ranks query"| node_search
node_daemon -->|"searches files"| node_files
node_daemon -->|"launches selection"| node_launch
node_daemon -->|"handles package action"| node_install
node_install -->|"searches catalog"| node_nixpkgs
node_install -->|"installs or removes"| node_profile
node_daemon -->|"updates pins"| node_pins
node_daemon -->|"updates groups"| node_groups
node_daemon -->|"saves state"| node_persistence
node_daemon -.->|"checks window overlap"| node_hyprland
node_hyprland -.->|"reports window state"| node_daemon

click node_ctl "https://github.com/maxpoww/launcher/blob/main/crates/client/src/main.rs"
click node_protocol "https://github.com/maxpoww/launcher/blob/main/crates/proto/src/lib.rs"
click node_daemon "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/main.rs"
click node_surface "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/renderer.rs"
click node_config "https://github.com/maxpoww/launcher/blob/main/crates/core/src/config.rs"
click node_appscan "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/apps.rs"
click node_search "https://github.com/maxpoww/launcher/blob/main/crates/core/src/search.rs"
click node_appindex "https://github.com/maxpoww/launcher/blob/main/crates/core/src/index.rs"
click node_files "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/files.rs"
click node_launch "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/launch.rs"
click node_install "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/install.rs"
click node_pins "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/pins.rs"
click node_groups "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/groups.rs"
click node_persistence "https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/persist.rs"

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_ctl,node_protocol,node_daemon,node_surface,node_config,node_user toneBlue
class node_appscan,node_search,node_appindex,node_files toneAmber
class node_launch,node_install,node_pins,node_groups,node_persistence toneMint
class node_wayland,node_hyprland,node_nixpkgs,node_profile toneRose
```

## Components

### Control and UI

- [Control CLI](https://github.com/maxpoww/launcher/blob/main/crates/client/src/main.rs): `crates/client/src/main.rs`
- [Command protocol](https://github.com/maxpoww/launcher/blob/main/crates/proto/src/lib.rs): `crates/proto/src/lib.rs`
- [Dock daemon](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/main.rs): `crates/daemon/src/main.rs`
- [Dock surface](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/renderer.rs): `crates/daemon/src/renderer.rs`
- [Configuration](https://github.com/maxpoww/launcher/blob/main/crates/core/src/config.rs): `crates/core/src/config.rs`

### Discovery and search

- [App discovery](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/apps.rs): `crates/daemon/src/apps.rs`
- [Fuzzy search](https://github.com/maxpoww/launcher/blob/main/crates/core/src/search.rs): `crates/core/src/search.rs`
- [App index](https://github.com/maxpoww/launcher/blob/main/crates/core/src/index.rs): `crates/core/src/index.rs`
- [File search](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/files.rs): `crates/daemon/src/files.rs`

### Launch and management

- [App launch](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/launch.rs): `crates/daemon/src/launch.rs`
- [Package management](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/install.rs): `crates/daemon/src/install.rs`
- [Dock pins](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/pins.rs): `crates/daemon/src/pins.rs`
- [App groups](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/groups.rs): `crates/daemon/src/groups.rs`
- [Saved state](https://github.com/maxpoww/launcher/blob/main/crates/daemon/src/persist.rs): `crates/daemon/src/persist.rs`

### Desktop integration

- **Wayland compositor**
- **Hyprland**
- **Nix package catalog**
- **Nix profile**

### Other components

- **User**

## Connections

- User → Control CLI: sends commands
- Control CLI → Command protocol: parses command
- Control CLI → Dock daemon: sends socket command
- Dock daemon → Command protocol: decodes command
- User → Dock surface: uses dock
- Dock surface → Dock daemon: sends input
- Dock daemon → Dock surface: updates display
- Dock daemon → Wayland compositor: creates surface
- Dock daemon → Configuration: loads settings
- Dock daemon → App discovery: requests rescan
- App discovery → App index: builds index
- Dock daemon → Fuzzy search: ranks query
- Dock daemon → File search: searches files
- Dock daemon → App launch: launches selection
- Dock daemon → Package management: handles package action
- Package management → Nix package catalog: searches catalog
- Package management → Nix profile: installs or removes
- Dock daemon → Dock pins: updates pins
- Dock daemon → App groups: updates groups
- Dock daemon → Saved state: saves state
- Dock daemon → Hyprland: checks window overlap
- Hyprland → Dock daemon: reports window state