Replace swaylock with gtklock; centralise theme palette

- Replace swaylock with gtklock (username + password form lockscreen) - Add gtklock/config.ini and gtklock/style.css (Tomorrow Night theme) - Update niri keybindings and swayidle to invoke gtklock -d - Update packages.txt: swaylock -> gtklock - Update install.sh: add AUR helper detection (yay/paru), symlink gtklock configs - Add theme/colors.css (CSS custom properties) and theme/colors.json - Update waybar/style.css, wofi/style.css, gtklock/style.css to import shared palette - Update README.md with project summary and component table - Add ARCHITECTURE.md and CLAUDE.md
2026-04-24 12:56:58 -07:00
parent 8c099437a4
commit 8be00bc273
12 changed files with 668 additions and 31 deletions
@@ -0,0 +1,286 @@
+# 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 |
+| 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.