From ed3ae30ed4826fdfa53b66cb7a831d634c5784bf Mon Sep 17 00:00:00 2001 From: uttarayan21 Date: Sun, 17 Aug 2025 01:32:11 +0530 Subject: [PATCH] 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 | 211 +++++++++++++++++++++++++++++++++ assets/devices-diagram.d2 | 235 +++++++++++++++++++++++++++++++++++++ assets/devices-diagram.svg | 149 +++++++++++++++++++++++ 3 files changed, 595 insertions(+) create mode 100644 DEVICE_ARCHITECTURE.md create mode 100644 assets/devices-diagram.d2 create mode 100644 assets/devices-diagram.svg diff --git a/DEVICE_ARCHITECTURE.md b/DEVICE_ARCHITECTURE.md new file mode 100644 index 00000000..ece4a438 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/assets/devices-diagram.d2 b/assets/devices-diagram.d2 new file mode 100644 index 00000000..6c30081d --- /dev/null +++ b/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 + } +} diff --git a/assets/devices-diagram.svg b/assets/devices-diagram.svg new file mode 100644 index 00000000..67f59789 --- /dev/null +++ b/assets/devices-diagram.svg @@ -0,0 +1,149 @@ +Device Architecture OverviewServer InfrastructureDevelopment WorkstationsPortable DevicesNetwork InfrastructureBuild MachinesConfiguration ManagementLegendmiraiMain Serverx86_64-linuxUser: fs0c131yHeadlessdeoxysVM Serverx86_64-linuxUser: serviusHeadlesstsubaRaspberry Piaarch64-linuxUser: serviusHeadlessryuMain Desktopx86_64-linuxUser: serviusHyprland + GNOMEkuroMacBookaarch64-darwinUser: fs0c131yshiroMacBookaarch64-darwinUser: serviusSteamDeckGaming Handheldx86_64-linuxUser: deckHome Manager OnlyTailscale VPNZeroTier NetworkLocal NetworkDistributed Buildsmirai, shiro (+ tsuba)NixOS FlakeHome Managernix-darwinšŸ–„ļø Servers (headless)šŸ’» Workstations (GUI)šŸ“± Portable/Mobileā†’ SSH DeployServicesā€¢ Nextcloudā€¢ Giteaā€¢ Grafanaā€¢ Minecraftā€¢ Immichā€¢ Paperlessā€¢ Tailscaleā€¢ And more...Multi-Monitor SetupHDMI-A-1(Gigabyte FO27Q3)DP-3(Acer XV272U)DP-1(Gigabyte M27Q) SSH DeploySSH DeploySSH Deploy(tsuba.darksailor.dev) SSH DeploySSH Deploy SSH Deploy(steamdeck) Uses distributed buildsUses distributed buildsBuild serverBuild server + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +