dotfiles/ARCHITECTURE.md

ARCHITECTURE.md

Overview

This system is a Wayland-first desktop environment built around the Niri compositor, designed for:

• Tiling workflow
• Keyboard-driven interaction
• Minimal background processes
• Clean separation between components

---

High-Level Architecture

                 ┌──────────────┐
                 │   greetd     │
                 │   + regreet  │
                 └──────┬───────┘
                        │
                        ▼
                 ┌──────────────┐
                 │     Niri     │
                 │ Compositor   │
                 └──────┬───────┘
        ┌───────────────┼────────────────┐
        ▼               ▼                ▼
   ┌────────┐     ┌────────┐      ┌──────────┐
   │ Waybar │     │  Mako  │      │  Wofi    │
   └────────┘     └────────┘      └──────────┘
        │               │                │
        ▼               ▼                ▼
   Status UI     Notifications     App Launcher

        ┌────────────────────────────────────┐
        ▼                                    ▼
   Alacritty                          GTK Apps / CLI
        │
        ▼
   Fish + Starship

---

Component Responsibilities

Niri (Core)

• Window management
• Input handling
• Layout control
• Workspace logic

Owns:

• Keybindings
• Window rules
• Focus behavior

---

Waybar (Status Layer)

• Displays system info (time, CPU, network, etc.)
• Acts as visual feedback layer

Design constraints:

• No heavy scripts
• Prefer event-driven updates

---

Mako (Notifications)

• Handles all desktop notifications

Rules:

• Short timeouts
• Minimal visual noise
• No stacking chaos

---

Wofi (Launcher)

• Application launcher + runner

Usage modes:

• drun (desktop apps)
• run (commands)

---

Terminal Stack

Alacritty

• GPU-accelerated terminal
• No tabs (delegated to WM)

Fish

• Interactive shell

Starship

• Prompt renderer

---

Session & Login

greetd + regreet

• Lightweight login manager
• Starts Niri session

---

Lock Screen

gtklock

• Simple Wayland-native lockscreen

---

Background Services

Function	Tool
Wallpaper	swww
Screenshots	grim + slurp + satty
Clipboard	cliphist

---

Data Flow

Startup Sequence

1. greetd starts

2. regreet authenticates user

3. Niri session launches

4. Autostart:

   • waybar
   • mako
   • swww
   • cliphist (if enabled)

---

User Interaction Flow

Launching Apps

Keybind → Wofi → Exec → Niri manages window

Notifications

App → DBus → Mako → Render

Status Updates

System → Waybar module → Display

---

Configuration Strategy

Centralized via Symlinks

~/.config/
├── niri/
├── waybar/
├── alacritty/
├── fish/
├── starship.toml
├── mako/
├── wofi/
└── gtklock/

All configs are sourced from the repo via:

install.sh → ln -s

---

Theming Architecture

Global Theme: Tomorrow Night

Applied consistently across:

• GTK (Materia-dark)
• Icons (Papirus)
• Terminal
• Waybar
• Wofi

Recommended Structure

theme/
├── colors.json (optional future)
├── gtk.css
├── waybar.css
└── wofi.css

---

Extensibility Model

Safe Extensions

• Add Waybar modules (lightweight)
• Add Wofi modes
• Extend Niri keybindings
• Add CLI tools

Risky Extensions

• Background daemons
• Polling scripts
• X11 compatibility layers
• Overly dynamic configs

---

Performance Considerations

• Avoid blocking shell scripts
• Keep Waybar modules lightweight
• Minimize startup processes
• Prefer static config over runtime logic

---

Failure Modes

Issue	Likely Cause
Black screen on login	Niri config error
Missing bar	Waybar not launched
No notifications	Mako not running
Slow shell	Fish config bloat

---

Future Improvements

• Shared theme variables across all tools
• Config templating (optional, must stay transparent)
• Per-host overrides
• Optional feature flags (minimal)

---

Guiding Philosophy

This system is:

• Predictable
• Minimal
• Fast
• Keyboard-first

Every addition must justify its existence.

If it adds complexity without clear benefit, it should not be included.