# iynaix/dotfiles architecture

> Architecture diagram of the GitHub repository iynaix/dotfiles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iynaix/dotfiles
- Repository: https://github.com/iynaix/dotfiles

## Overview

This repository is a configuration-based project for NixOS and Home Manager, used to manage NixOS systems—including desktops, laptops, VMs and even legacy operating systems—with a heavy emphasis on modular configuration, system recovery, persistence management (via impermanence and ZFS snapshots), and dynamic theming. The project also includes installation and recovery scripts, as well as custom packages and overlays for fine-tuning the system behavior.

##### And Label Main Components
- NixOS Base Configuration: Represented by the “nixos” directory (files like configuration.nix, audio.nix, boot.nix, etc.). This is the core system configuration that bootstraps and customizes the operating system.
- Home Manager/User Environment: Represented by the “home-manager” directory, which holds user-specific configurations. Show its division into “gui”, “hyprland”, “shell”, etc. as sub-components.
- Installation and Recovery Tools: Include the install scripts (install.sh) and recovery script (recover.sh) as components that trigger processes to set up and rescue the system.
- Overlays and Custom Packages: Represent the “overlays” and “packages” directories. These are used to extend or modify the behavior of NixOS/nixpkgs and provide various functionality such as custom dotfiles management, Hyprnstack, and other specialized utilities.
- Persistence and Secret Management: Include elements for impermanence (handling non-persistent data using ZFS snapshots) and sops-nix (for managing secrets), as mentioned in the README.

- Home Manager configuration under “home-manager” to the system user environment, and show it as a layer on top of the base system.
- Link the “overlays” and “packages” components to both the NixOS and Home Manager setups, illustrating their roles in customizing and extending functionality.
- Communication between the configuration files and external tools like ZFS for snapshots (persistence) and sops-nix (for secrets), to indicate data flow and dependency management.

##### Architectural Patterns and Design Principles
- Modularization: The project splits configurations per component (NixOS vs. Home Manager vs. hosts) and further subdivides based on system roles.
- Separation of concerns: Distinguish between system-level configuration (NixOS) and user-level settings (Home Manager/dotfiles).
- Reusability: Custom overlays and packages indicate an intention to reuse and extend functionality without duplicating code.
- Extensibility: The layered approach (configuration → customization via overlays and packages) allows for flexible modifications and is key to the project’s design.

##### Important Technologies & Tools
- NixOS: The operating system and its declarative configuration.
- Home Manager: For managing user configurations.
- ZFS: Handling persistence with snapshot creation/rotation.
- sops-nix: For managing secrets securely.
- Hyprland, Waybar, and various GUI-related assets: Showing specialized configurations for desktop environments.
- Nix and flake: For reproducible builds and dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Installation and Recovery Tools
    subgraph "Installation & Recovery"
        Install["Install Script<br/>(Sets up system)"]:::system
        Recovery["Recovery Script<br/>(System rescue)"]:::system
    end

    %% System Level Configurations
    subgraph "System-Level Configurations"
        Nxos["NixOS Base Configuration<br/>(Core OS config: hardware, boot, services)"]:::system
        Hosts["Hosts Specific Configurations<br/>(Per-host customization and hardware settings)"]:::system
    end

    %% User-Level Environment
    subgraph "User-Level Environment"
        HM["Home Manager/User Environment<br/>(User-specific config & dotfiles)"]:::user
    end

    %% Extensions: Overlays & Packages (Integration Components)
    subgraph "Extensions"
        Overlays["Overlays<br/>(Custom overlays for nixpkgs)"]:::integration
        Packages["Packages<br/>(Custom packages and utilities)"]:::integration
    end

    %% Persistence and Secret Management
    subgraph "Persistence & Secret Management"
        Impermanence_Nixos["Impermanence (NixOS)<br/>(Non-persistent data, ZFS snapshots)"]:::storage
        Impermanence_HM["Impermanence (Home Manager)<br/>(Non-persistent user data)"]:::storage
        Secrets_Nixos["Secrets Management (NixOS)<br/>(sops-nix for secrets)"]:::storage
        Secrets_Hosts["Secrets Management (Hosts)<br/>(Host-specific secrets)"]:::storage
    end

    %% Connections from Installation & Recovery to System-Level Configurations
    Install -->|"deploys"| Nxos
    Install -->|"deploys"| Hosts
    Recovery -->|"can restore"| Nxos
    Recovery -->|"can restore"| Hosts

    %% Layering from NixOS to Home Manager
    Nxos -->|"supports"| HM

    %% Extensions linking to both system and user environments
    Overlays ---|"extends"| Nxos
    Overlays ---|"extends"| HM
    Packages ---|"supplies"| Nxos
    Packages ---|"supplies"| HM

    %% Persistence and Secrets connections
    Nxos -->|"integrates"| Impermanence_Nixos
    HM -->|"integrates"| Impermanence_HM
    Nxos -->|"secures"| Secrets_Nixos
    Hosts -->|"secures"| Secrets_Hosts

    %% Styling Classes
    classDef system fill:#FFDDCC,stroke:#B44,stroke-width:2px;
    classDef user fill:#CCFFCC,stroke:#484,stroke-width:2px;
    classDef integration fill:#CCCCFF,stroke:#444,stroke-width:2px;
    classDef storage fill:#FFD700,stroke:#AA0,stroke-width:2px;

    %% Click Events
    click Nxos "https://github.com/iynaix/dotfiles/tree/main/nixos/"
    click HM "https://github.com/iynaix/dotfiles/tree/main/home-manager/"
    click Hosts "https://github.com/iynaix/dotfiles/tree/main/hosts/"
    click Install "https://github.com/iynaix/dotfiles/blob/main/install.sh"
    click Recovery "https://github.com/iynaix/dotfiles/blob/main/recover.sh"
    click Overlays "https://github.com/iynaix/dotfiles/tree/main/overlays/"
    click Packages "https://github.com/iynaix/dotfiles/tree/main/packages/"
    click Impermanence_Nixos "https://github.com/iynaix/dotfiles/blob/main/nixos/impermanence.nix"
    click Impermanence_HM "https://github.com/iynaix/dotfiles/blob/main/home-manager/impermanence.nix"
    click Secrets_Nixos "https://github.com/iynaix/dotfiles/blob/main/nixos/sops.nix"
    click Secrets_Hosts "https://github.com/iynaix/dotfiles/blob/main/hosts/secrets.json"
```
