# bra0/niri-mods architecture

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

- Interactive diagram: https://gitdiagram.com/bra0/niri-mods
- Repository: https://github.com/bra0/niri-mods

## Overview

niri-mods is a Linux daemon for niri that combines keyboard chord modes with Waybar visibility control. The main workflow is: Mod plus a leader enters a configured mode, grabs keyboards, and displays a binding hint; a bound key launches its command, while cancellation, timeout, or reload exits the mode and releases keyboards. The daemon also handles toggle requests and hot-reloads KDL configuration. Relationships below follow the excerpts and README; unsampled details of the shipped configuration and external programs are not expanded.

Main entry points: [`src/main.rs`](https://github.com/bra0/niri-mods/blob/main/src/main.rs) (Event loop), [`src/keys.rs`](https://github.com/bra0/niri-mods/blob/main/src/keys.rs) (Keyboard reader), [`src/waybar.rs`](https://github.com/bra0/niri-mods/blob/main/src/waybar.rs) (Waybar process), [`src/state.rs`](https://github.com/bra0/niri-mods/blob/main/src/state.rs) (Event types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Daemon runtime"]
  node_cli["CLI<br/>[main.rs]"]
  node_daemon["Event loop<br/>[main.rs]"]
  node_events["Event types<br/>[state.rs]"]
  node_ipc["Socket control<br/>[ipc.rs]"]
  node_watcher["Config watcher<br/>[watch.rs]"]
end

subgraph group_input["Keyboard input"]
  node_keyboard["Keyboard reader<br/>[keys.rs]"]
end

subgraph group_config["Modes and configuration"]
  node_config["KDL config<br/>[config.rs]"]
end

subgraph group_integrations["Desktop integrations"]
  node_niri["niri compositor"]
  node_waybar["Waybar process<br/>[waybar.rs]"]
  node_foot["foot hint window<br/>[hint.rs]"]
end

node_user(("User"))
node_inputdev["Linux keyboards"]

node_user -->|"runs command"| node_cli
node_cli -->|"sends toggle"| node_ipc
node_cli -->|"starts daemon"| node_daemon
node_daemon -->|"starts listener"| node_ipc
node_daemon -->|"starts readers"| node_keyboard
node_daemon -->|"starts polling"| node_watcher
node_daemon -->|"loads and reloads"| node_config
node_keyboard -->|"reads events"| node_inputdev
node_keyboard -->|"sends key events"| node_events
node_ipc -->|"sends toggle"| node_events
node_watcher -->|"sends reload"| node_events
node_daemon -->|"handles events"| node_events
node_daemon -->|"grabs and releases"| node_keyboard
node_daemon -->|"looks up modes"| node_config
node_daemon -->|"shows hint"| node_foot
node_daemon -->|"spawns commands"| node_niri
node_daemon -->|"controls visibility"| node_waybar
node_waybar -->|"reloads config"| node_niri
node_waybar -->|"signals process"| node_waybar

click node_cli "https://github.com/bra0/niri-mods/blob/main/src/main.rs"
click node_daemon "https://github.com/bra0/niri-mods/blob/main/src/main.rs"
click node_events "https://github.com/bra0/niri-mods/blob/main/src/state.rs"
click node_ipc "https://github.com/bra0/niri-mods/blob/main/src/ipc.rs"
click node_watcher "https://github.com/bra0/niri-mods/blob/main/src/watch.rs"
click node_keyboard "https://github.com/bra0/niri-mods/blob/main/src/keys.rs"
click node_config "https://github.com/bra0/niri-mods/blob/main/src/config.rs"
click node_waybar "https://github.com/bra0/niri-mods/blob/main/src/waybar.rs"
click node_foot "https://github.com/bra0/niri-mods/blob/main/src/hint.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_cli,node_daemon,node_events,node_ipc,node_watcher,node_user toneBlue
class node_keyboard toneAmber
class node_config toneMint
class node_niri,node_waybar,node_foot toneRose
class node_inputdev toneIndigo
```

## Components

### Daemon runtime

- [CLI](https://github.com/bra0/niri-mods/blob/main/src/main.rs): `src/main.rs`
- [Event loop](https://github.com/bra0/niri-mods/blob/main/src/main.rs): `src/main.rs`
- [Event types](https://github.com/bra0/niri-mods/blob/main/src/state.rs): `src/state.rs`
- [Socket control](https://github.com/bra0/niri-mods/blob/main/src/ipc.rs): `src/ipc.rs`
- [Config watcher](https://github.com/bra0/niri-mods/blob/main/src/watch.rs): `src/watch.rs`

### Keyboard input

- [Keyboard reader](https://github.com/bra0/niri-mods/blob/main/src/keys.rs): `src/keys.rs`

### Modes and configuration

- [KDL config](https://github.com/bra0/niri-mods/blob/main/src/config.rs): `src/config.rs`

### Desktop integrations

- **niri compositor**
- [Waybar process](https://github.com/bra0/niri-mods/blob/main/src/waybar.rs): `src/waybar.rs`
- [foot hint window](https://github.com/bra0/niri-mods/blob/main/src/hint.rs): `src/hint.rs`

### Other components

- **User**
- **Linux keyboards**

## Connections

- User → CLI: runs command (evidence: `README.md`)
- CLI → Socket control: sends toggle (evidence: `src/main.rs`)
- CLI → Event loop: starts daemon (evidence: `src/main.rs`)
- Event loop → Socket control: starts listener (evidence: `src/main.rs`)
- Event loop → Keyboard reader: starts readers (evidence: `src/main.rs`)
- Event loop → Config watcher: starts polling (evidence: `src/main.rs`)
- Event loop → KDL config: loads and reloads (evidence: `src/main.rs`)
- Keyboard reader → Linux keyboards: reads events (evidence: `src/keys.rs`)
- Keyboard reader → Event types: sends key events (evidence: `src/keys.rs`)
- Socket control → Event types: sends toggle (evidence: `src/ipc.rs`)
- Config watcher → Event types: sends reload (evidence: `src/watch.rs`)
- Event loop → Event types: handles events (evidence: `src/main.rs`)
- Event loop → Keyboard reader: grabs and releases (evidence: `src/main.rs`)
- Event loop → KDL config: looks up modes (evidence: `src/main.rs`)
- Event loop → foot hint window: shows hint (evidence: `src/main.rs`)
- Event loop → niri compositor: spawns commands (evidence: `src/main.rs`)
- Event loop → Waybar process: controls visibility (evidence: `src/main.rs`)
- Waybar process → niri compositor: reloads config (evidence: `src/waybar.rs`)
- Waybar process → Waybar process: signals process (evidence: `src/waybar.rs`)
