Add device architecture documentation and D2 diagram

- Add comprehensive DEVICE_ARCHITECTURE.md with detailed device specifications
- Create D2 diagram showing device relationships and network topology
- Organize assets in dedicated assets/ folder
- Document all devices: servers (mirai, deoxys, tsuba), workstations (ryu),
  and portable devices (kuro, shiro, SteamDeck)
- Include deployment flows, network architecture, and build infrastructure

DEVICE_ARCHITECTURE.md

@@ -0,0 +1,211 @@
+# Device Architecture Overview
+
+This document provides a comprehensive overview of all devices managed by this NixOS/nix-darwin dotfiles repository.
+
+> **Visual Diagram**: See [assets/devices-diagram.svg](assets/devices-diagram.svg) for a visual representation of this architecture.
+
+## Device Categories
+
+### 🖥️ Server Infrastructure (Headless)
+
+#### mirai (Main Server)
+- **Architecture**: x86_64-linux
+- **User**: fs0c131y
+- **Role**: Primary server hosting various services
+- **Configuration**: NixOS + Home Manager
+- **Hardware**: AMD CPU with NVME storage
+- **Location**: Local network
+- **Services**:
+  - Nextcloud (file storage and sync)
+  - Gitea (Git hosting)
+  - Grafana (monitoring and dashboards)
+  - Minecraft server
+  - Immich (photo management)
+  - Paperless (document management)
+  - Tailscale VPN node
+  - ZeroTier network node
+  - Atuin (shell history sync)
+  - LLDAP (LDAP server)
+  - Navidrome (music streaming)
+  - Searxng (search engine)
+  - Syncthing
+  - And many more services
+
+#### deoxys (VM Server)
+- **Architecture**: x86_64-linux
+- **User**: servius
+- **Role**: Virtual machine server for testing and isolation
+- **Configuration**: NixOS + Home Manager
+- **Location**: Local network
+
+#### tsuba (Raspberry Pi)
+- **Architecture**: aarch64-linux
+- **User**: servius
+- **Role**: ARM-based server for lightweight services
+- **Configuration**: NixOS + Home Manager (using stable channel)
+- **Hardware**: Raspberry Pi
+- **Access**: External via tsuba.darksailor.dev
+- **Special**: Uses nixos-raspberrypi input for hardware support
+
+### 💻 Development Workstations
+
+#### ryu (Main Desktop)
+- **Architecture**: x86_64-linux
+- **User**: servius
+- **Role**: Primary development workstation
+- **Configuration**: NixOS + Home Manager
+- **Desktop Environment**: Hyprland (primary) + GNOME (fallback)
+- **Features**:
+  - Multi-monitor setup:
+    - Primary: HDMI-A-1 (Gigabyte FO27Q3)
+    - Secondary: DP-3 (Acer XV272U)
+    - Tertiary: DP-1 (Gigabyte M27Q)
+  - Audio production setup (musnix)
+  - Gaming support (Wine, Steam)
+  - Virtualization (virt-manager)
+  - Hardware acceleration (CUDA support)
+  - Secure boot with Lanzaboote
+  - TPM2 support
+
+### 📱 Portable/Mobile Devices
+
+#### kuro (MacBook)
+- **Architecture**: aarch64-darwin (Apple Silicon)
+- **User**: fs0c131y
+- **Role**: macOS development machine
+- **Configuration**: nix-darwin + Home Manager
+- **Features**:
+  - Touch ID for sudo authentication
+  - Custom keyboard mappings
+  - Homebrew integration
+
+#### shiro (MacBook)
+- **Architecture**: aarch64-darwin (Apple Silicon)
+- **User**: servius
+- **Role**: Secondary macOS machine
+- **Configuration**: nix-darwin + Home Manager
+
+#### SteamDeck (Gaming Handheld)
+- **Architecture**: x86_64-linux
+- **User**: deck
+- **Role**: Portable gaming device
+- **Configuration**: Home Manager only (no NixOS)
+- **Special**: Uses SteamOS with Home Manager overlay
+
+## Network Architecture
+
+### VPN Networks
+- **Tailscale**: Primary VPN connecting most devices
+  - Devices: mirai, deoxys, tsuba, deck
+- **ZeroTier**: Secondary network layer
+  - Devices: mirai, ryu
+
+### Local Network
+- **Primary connection**: ryu (main desktop)
+- **Wake-on-LAN**: Enabled for ryu (eno1 interface)
+
+## Configuration Management
+
+### NixOS Flake
+- **Manages**: mirai, deoxys, tsuba, ryu
+- **Features**: Unified configuration across Linux devices
+- **Inputs**: Multiple flake inputs for extended functionality
+
+### nix-darwin
+- **Manages**: kuro, shiro
+- **Features**: macOS system configuration
+
+### Home Manager
+- **Standalone**: deck (SteamDeck)
+- **Integrated**: All other devices
+- **Stable channel**: Used for tsuba
+
+## Build Infrastructure
+
+### Distributed Building
+- **Build machines**: 
+  - mirai (primary build server)
+  - shiro (macOS builds)
+  - tsuba (ARM builds, commented out)
+- **Consumers**: 
+  - ryu (uses remote builders)
+  - kuro (uses remote builders)
+
+### Cache Strategy
+- **Substituters**:
+  - nix-community.cachix.org
+  - nixos-raspberrypi.cachix.org (for ARM builds)
+- **Build optimization**: Auto-optimise-store enabled
+
+## Deployment Strategy
+
+### SSH-based Deployment
+Using deploy-rs for automated deployments:
+
+```
+ryu → mirai, deoxys, tsuba, deck
+kuro → mirai, shiro
+```
+
+### Special Access
+- **tsuba**: Accessed via external domain (tsuba.darksailor.dev)
+- **All servers**: SSH key authentication with authorized_keys
+
+## Hardware-Specific Features
+
+### ryu (Desktop)
+- **Graphics**: NVIDIA with CUDA support
+- **Audio**: Professional audio setup with musnix
+- **Input devices**: QMK keyboard support
+- **Monitors**: DDC/CI control with ddcutil
+- **Security**: TPM2, secure boot (Lanzaboote)
+
+### mirai (Server)
+- **CPU**: AMD with virtualization support
+- **Storage**: Custom disk layout with disko
+- **Containers**: Docker with custom mount points
+- **Emulation**: aarch64-linux binfmt support
+
+### macOS Devices (kuro, shiro)
+- **Authentication**: Touch ID integration
+- **Keyboard**: Custom modifier key mappings
+- **Package management**: Homebrew + Nix hybrid approach
+
+## Security Features
+
+- **SOPS**: Secrets management across all devices
+- **SSH keys**: Centralized key management
+- **Fail2ban**: Enabled on mirai
+- **Secure boot**: Implemented on ryu
+- **TPM**: Hardware security on ryu
+
+## Development Environment
+
+### Shared Tools
+- **Editor**: Nixvim (custom Neovim configuration)
+- **Shell**: Fish + Nushell support
+- **Terminal**: Various per-device preferences
+- **Version control**: Git with shared configuration
+
+### Language Support
+- **Rust**: Custom overlay with latest toolchain
+- **Python**: Python 3 with development tools
+- **Nix**: Latest Nix with flakes enabled
+- **Web**: Node.js and web development tools
+
+## Monitoring and Observability
+
+- **Grafana**: Centralized monitoring on mirai
+- **System metrics**: Collected across all NixOS devices
+- **Shell history**: Synchronized via Atuin
+- **File synchronization**: Syncthing for selective sync
+
+## Backup and Data Management
+
+- **Nextcloud**: Primary cloud storage on mirai
+- **Syncthing**: Decentralized file sync
+- **Git repositories**: Self-hosted on Gitea (mirai)
+- **Photos**: Immich for photo management
+- **Documents**: Paperless for document archival
+
+This architecture provides a robust, scalable, and maintainable infrastructure for development, gaming, media consumption, and server hosting across multiple platforms and architectures.

assets/devices-diagram.d2

@@ -0,0 +1,235 @@
+title: Device Architecture Overview {
+  near: top-center
+  shape: text
+  style: {
+    font-size: 24
+    bold: true
+  }
+}
+
+# Device Groups
+servers: Server Infrastructure {
+  style.fill: "#e8f4fd"
+  style.stroke: "#1e3a8a"
+  style.stroke-width: 2
+
+  mirai: mirai {
+    shape: rectangle
+    style.fill: "#fbbf24"
+
+    label: "mirai\nMain Server\nx86_64-linux\nUser: fs0c131y\nHeadless"
+
+    services: Services {
+      shape: cylinder
+      style.fill: "#34d399"
+      label: "Services\n• Nextcloud\n• Gitea\n• Grafana\n• Minecraft\n• Immich\n• Paperless\n• Tailscale\n• And more..."
+    }
+  }
+
+  deoxys: deoxys {
+    shape: rectangle
+    style.fill: "#a78bfa"
+    label: "deoxys\nVM Server\nx86_64-linux\nUser: servius\nHeadless"
+  }
+
+  tsuba: tsuba {
+    shape: rectangle
+    style.fill: "#fb7185"
+    label: "tsuba\nRaspberry Pi\naarch64-linux\nUser: servius\nHeadless"
+  }
+}
+
+workstations: Development Workstations {
+  style.fill: "#f0fdf4"
+  style.stroke: "#15803d"
+  style.stroke-width: 2
+
+  ryu: ryu {
+    shape: rectangle
+    style.fill: "#3b82f6"
+    label: "ryu\nMain Desktop\nx86_64-linux\nUser: servius\nHyprland + GNOME"
+
+    monitors: Multi-Monitor Setup {
+      style.fill: "#ddd6fe"
+
+      primary: "HDMI-A-1\n(Gigabyte FO27Q3)" {
+        shape: rectangle
+        style.fill: "#c4b5fd"
+      }
+      secondary: "DP-3\n(Acer XV272U)" {
+        shape: rectangle
+        style.fill: "#c4b5fd"
+      }
+      tertiary: "DP-1\n(Gigabyte M27Q)" {
+        shape: rectangle
+        style.fill: "#c4b5fd"
+      }
+    }
+  }
+}
+
+mobile: Portable Devices {
+  style.fill: "#fef3c7"
+  style.stroke: "#d97706"
+  style.stroke-width: 2
+
+  kuro: kuro {
+    shape: rectangle
+    style.fill: "#6b7280"
+    label: "kuro\nMacBook\naarch64-darwin\nUser: fs0c131y"
+  }
+
+  shiro: shiro {
+    shape: rectangle
+    style.fill: "#9ca3af"
+    label: "shiro\nMacBook\naarch64-darwin\nUser: servius"
+  }
+
+  deck: SteamDeck {
+    shape: rectangle
+    style.fill: "#ef4444"
+    label: "SteamDeck\nGaming Handheld\nx86_64-linux\nUser: deck\nHome Manager Only"
+  }
+}
+
+# Network Infrastructure
+network: Network Infrastructure {
+  style.fill: "#fdf2f8"
+  style.stroke: "#db2777"
+  style.stroke-width: 2
+
+  tailscale: Tailscale VPN {
+    shape: cloud
+    style.fill: "#ec4899"
+  }
+
+  zerotier: ZeroTier Network {
+    shape: cloud
+    style.fill: "#f97316"
+  }
+
+  local_network: Local Network {
+    shape: cloud
+    style.fill: "#06b6d4"
+  }
+}
+
+# Build Infrastructure
+builders: Build Machines {
+  style.fill: "#f5f5f4"
+  style.stroke: "#525252"
+  style.stroke-width: 2
+
+  build_info: "Distributed Builds\nmirai, shiro (+ tsuba)" {
+    shape: text
+    style.font-size: 14
+    style.bold: true
+  }
+}
+
+# Configuration Management
+config_mgmt: Configuration Management {
+  style.fill: "#fefce8"
+  style.stroke: "#ca8a04"
+  style.stroke-width: 2
+
+  nixos_flake: NixOS Flake {
+    shape: hexagon
+    style.fill: "#facc15"
+  }
+
+  home_manager: Home Manager {
+    shape: hexagon
+    style.fill: "#eab308"
+  }
+
+  darwin: nix-darwin {
+    shape: hexagon
+    style.fill: "#f59e0b"
+  }
+}
+
+# Deployment Connections
+workstations.ryu -> servers.mirai: SSH Deploy {
+  style.stroke: "#059669"
+  style.stroke-width: 2
+}
+
+workstations.ryu -> servers.deoxys: SSH Deploy {
+  style.stroke: "#059669"
+  style.stroke-width: 2
+}
+
+workstations.ryu -> servers.tsuba: "SSH Deploy\n(tsuba.darksailor.dev)" {
+  style.stroke: "#059669"
+  style.stroke-width: 2
+}
+
+mobile.kuro -> servers.mirai: SSH Deploy {
+  style.stroke: "#7c3aed"
+  style.stroke-width: 2
+}
+
+mobile.kuro -> mobile.shiro: SSH Deploy {
+  style.stroke: "#7c3aed"
+  style.stroke-width: 2
+}
+
+workstations.ryu -> mobile.deck: "SSH Deploy\n(steamdeck)" {
+  style.stroke: "#dc2626"
+  style.stroke-width: 2
+}
+
+# Network connections
+servers.mirai -> network.tailscale
+servers.deoxys -> network.tailscale
+servers.tsuba -> network.tailscale
+workstations.ryu -> network.local_network
+mobile.deck -> network.tailscale
+
+servers.mirai -> network.zerotier
+workstations.ryu -> network.zerotier
+
+# Build relationships
+workstations.ryu -> builders: Uses distributed builds
+mobile.kuro -> builders: Uses distributed builds
+servers.mirai -> builders: Build server
+mobile.shiro -> builders: Build server
+
+# Configuration connections
+config_mgmt.nixos_flake -> servers.mirai
+config_mgmt.nixos_flake -> servers.deoxys
+config_mgmt.nixos_flake -> servers.tsuba
+config_mgmt.nixos_flake -> workstations.ryu
+
+config_mgmt.darwin -> mobile.kuro
+config_mgmt.darwin -> mobile.shiro
+
+config_mgmt.home_manager -> mobile.deck
+
+# Legend
+legend: Legend {
+  near: bottom-right
+  style.fill: "#f9fafb"
+  style.stroke: "#6b7280"
+
+  servers_legend: "🖥️ Servers (headless)" {
+    shape: text
+    style.font-size: 12
+  }
+
+  workstations_legend: "💻 Workstations (GUI)" {
+    shape: text
+    style.font-size: 12
+  }
+
+  mobile_legend: "📱 Portable/Mobile" {
+    shape: text
+    style.font-size: 12
+  }
+
+  deploy_legend: "→ SSH Deploy" {
+    shape: text
+    style.font-size: 12
+  }
+}