# 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.