# nanamiiiii/dotfiles architecture

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

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

## Overview

##### Main Components
- Repository Core – the central dotfiles repository that contains all configuration files.
- Nix-based Configuration Cluster – this includes directories like home-manager, nix-darwin, nix-wsl, and nixos. These parts together define your system integration for NixOS and related distributions. Within this cluster, further distinguish:
- Home-manager: user-level configurations for various applications.
- NixOS/nix-darwin/nix-wsl: system-level settings and packages.
- Profiles: different profiles for various users or machines (e.g., asu, mafu, rika, saki, yuki, etc.).
- Overlays and packages: custom packages or modifications applied on top of the standard Nix packages.
- Non-Nix Configuration Cluster – this includes configurations and tools such as:
- aqua: a tool with its own configuration file (aqua.yaml) and associated checksum file.
- sheldon: plugin configurations for the shell.
- The extensive "config" directory: contains configurations for window managers (i3, hypr, sway, etc.), terminal emulators, fonts, display managers, and various utility scripts.

##### Relationships and Interactions
- The dotfiles repository acts as the single source of truth.
- In the Nix-based cluster, the various Nix configuration files (in directories like nixos, home-manager, nix-darwin) are applied through the Nix build and deployment system. This is accomplished by integrating the profiles and overlays, which in turn, pull in and manage the configuration details for different systems (desktop, WSL, etc.).
- The non-Nix configurations are applied manually or through lightweight deployment scripts. They define the settings for individual applications and utilities.
- Although these clusters function separately, they are all maintained within one repository to standardize and simplify configuration management.

##### Architectural Patterns and Design Principles
- Modularity: the repository is broken down into logical modules (e.g., home-manager, nix-darwin, config, profiles). Each module is self-contained and tailored to a specific component.
- Separation of Concerns: clearly divide Nix-based system configurations from non-Nix configurations.
- Hierarchical Organization: within directories like “config” or “home-manager”, configurations are organized by application or function (e.g., window managers, terminals, multimedia, etc.), which simplifies updates and maintenance.

##### Relevant Technologies and Frameworks
- Nix/NixOS – deep integration for system configuration, with dedicated directories for OS-level settings and home-manager for user-level configurations.
- Profiles and Overlays – used for customization and managing differences between various system setups.
- Aqua and Sheldon – separate non-Nix tools used to manage additional aspects of system configuration (such as checksum verifications with aqua and shell plugin management with sheldon).
- Various Unix/Linux utilities and scripts (e.g., Makefile, shell scripts) that automate parts of the deployment and customization process.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Central Repository Node
    Core["Dotfiles Repository"]:::core

    %% Nix-based Configurations Cluster
    subgraph "Nix-based Configurations"
        HM["home-manager (User-level)"]:::nix
        Nixos["nixos (System-level)"]:::nix
        Darwin["nix-darwin (macOS)"]:::nix
        WSL["nix-wsl (WSL)"]:::nix
        Profiles["Profiles (User/Machine)"]:::nix
        Overlays["Overlays (Custom Packages)"]:::nix
        Packages["Packages (Custom Nix Packages)"]:::nix
    end

    %% Non-Nix Configurations Cluster
    subgraph "Non-Nix Configurations"
        Aqua["aqua (Tool config)"]:::nonnix
        Sheldon["sheldon (Shell plugins)"]:::nonnix
        Config["config (Application configs)"]:::nonnix
    end

    %% Deployment Nodes
    Deployment["Nix Build & Deployment"]:::deployment
    Manual["Manual/Scripted Deployment"]:::deployment

    %% Relationships from Dotfiles Repository to Modules
    Core -->|"pushes"| HM
    Core -->|"pushes"| Nixos
    Core -->|"pushes"| Darwin
    Core -->|"pushes"| WSL
    Core -->|"pushes"| Profiles
    Core -->|"pushes"| Overlays
    Core -->|"pushes"| Packages
    Core -->|"pushes"| Aqua
    Core -->|"pushes"| Sheldon
    Core -->|"pushes"| Config

    %% Deployment Relationships for Nix-based Configurations
    HM -->|"applied_by"| Deployment
    Nixos -->|"applied_by"| Deployment
    Darwin -->|"applied_by"| Deployment
    WSL -->|"applied_by"| Deployment
    Profiles -->|"integrated_into"| Deployment
    Overlays -->|"integrated_into"| Deployment
    Packages -->|"integrated_into"| Deployment

    %% Deployment Relationships for Non-Nix Configurations
    Aqua -->|"applied_by"| Manual
    Sheldon -->|"applied_by"| Manual
    Config -->|"applied_by"| Manual

    %% Click Events for Components
    click Core "https://github.com/nanamiiiii/dotfiles/tree/main/Root of the repository"
    click HM "https://github.com/nanamiiiii/dotfiles/tree/main/home-manager/"
    click Nixos "https://github.com/nanamiiiii/dotfiles/tree/main/nixos/"
    click Darwin "https://github.com/nanamiiiii/dotfiles/tree/main/nix-darwin/"
    click WSL "https://github.com/nanamiiiii/dotfiles/tree/main/nix-wsl/"
    click Profiles "https://github.com/nanamiiiii/dotfiles/tree/main/profiles/"
    click Overlays "https://github.com/nanamiiiii/dotfiles/tree/main/overlays/"
    click Packages "https://github.com/nanamiiiii/dotfiles/tree/main/packages/"
    click Aqua "https://github.com/nanamiiiii/dotfiles/tree/main/aqua/"
    click Sheldon "https://github.com/nanamiiiii/dotfiles/tree/main/sheldon/"
    click Config "https://github.com/nanamiiiii/dotfiles/tree/main/config/"

    %% Styles
    classDef core fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef nix fill:#A2D2FF,stroke:#333,stroke-width:2px;
    classDef nonnix fill:#FFC4C4,stroke:#333,stroke-width:2px;
    classDef deployment fill:#CAFFBF,stroke:#333,stroke-width:2px;
```
