# jeremiealcaraz/nixos-config architecture

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

- Interactive diagram: https://gitdiagram.com/jeremiealcaraz/nixos-config
- Repository: https://github.com/jeremiealcaraz/nixos-config

## Overview

##### Project Type and Purpose
- This repository is an infrastructure-as-code project using Nix flakes to define a reproducible NixOS system and user (Home Manager) configurations across multiple hosts (Mac, NixOS laptops).
- It’s not a typical “application” but a declarative system configuration with clear separation of OS modules, user modules, package overlays, and per-host definitions.

##### File Structure Analysis
- Root files
- flake.nix, flake.lock, shell.nix: entry point for Nix flakes.
- justfile: task runner shortcuts (`just bs`, `just hs`).
- README, assets/: documentation and visuals.
- Directories
- modules/home-manager and modules/nixos: reusable module sets for user and system configurations.
- hosts/: one subdirectory per machine, each with default.nix and hardware-configuration.nix for that host.
- overlays/: custom Nix package overrides.
- pkgs/: custom or “latest” package definitions fetched or built locally.
- home/, home/common/: local Nix expressions for shared user configurations (e.g., CLI app configs, shell configs, fonts).

##### README Insights
- Emphasizes NixOS + Home Manager with flakes.
- Lists runtime components: Niri WM, Hyprland, Waybar, Ghostty & Kitty terminals, Zsh with Antidote & oh-my-posh, Walker launcher, Catppuccin theme, Monaspace font, Neovim.

##### Main Components
a. Flake Layer
- flake.nix (root)
- shell.nix, justfile (developer entry points)
b. Module Layer
- modules/nixos (system modules)
- modules/home-manager (user modules)
- home/common/core and home/common/optional (shared user configurations)
c. Overlay & Package Layer
- overlays/default.nix (overrides)
- pkgs/* (custom package definitions)
d. Host Layer
- hosts/<host>/default.nix (system configuration for each machine)
- hosts/<host>/hardware-configuration.nix
e. Runtime Layer (Actual components installed/managed at runtime)
- Window Managers: Niri, Hyprland
- Status Bar: Waybar
- Terminals: Ghostty, Kitty
- Shell: Zsh + Antidote + oh-my-posh
- Launcher: Walker
- Editor: Neovim
- Themes & Fonts: Catppuccin, Monaspace

##### Relationships and Data Flows
- The Flake entry point references Module Layer and Overlay & Package Layer.
- Module Layer provides reusable Nix expressions imported by each host’s default.nix.
- Overlay & Package Layer customizes or adds OCIs (Nix derivations) used by both host and user modules.
- Each hosts/<host>/default.nix imports modules/nixos, home-manager modules, overlays, pkgs, and home/common.
- During a `nixos-rebuild switch --flake .#<host>`, Nix builds a NixOS system derivation using those inputs.
- During `home-manager switch --flake .#<user>@<host>`, Nix builds user-level dotfiles and services via home-manager modules.
- At runtime, user sees the Window Manager, terminals, shell, launcher, status bar, and editor configured by those derivations.

##### Architectural Patterns and Principles
- Declarative, layered configuration: clear separation of concerns (OS modules vs. user modules).
- DRY via shared `modules/` and `home/common/` directories.
- Reproducibility: all dependencies (packages, overlays) are declared in the flake.
- Host-specific overrides: each host directory tailors hardware settings and secrets.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flake Layer
    subgraph "Flake Layer"
        FLK_nix["flake.nix"] 
        FLK_lock["flake.lock"]
        SHNIX["shell.nix"]
        JUST["justfile"]
    end

    %% Module Layer
    subgraph "Module Layer"
        NIXOS_MODULES["modules/nixos/default.nix"]
        HOME_MODULES["modules/home-manager/default.nix"]
        CORE_COMMON["home/common/core/default.nix"]
        OPTIONAL_COMMON["home/common/optional/default.nix"]
    end

    %% Overlay & Package Layer
    subgraph "Overlay & Package Layer"
        OVERLAYS["overlays/default.nix"]
        PKGS_DEFAULT["pkgs/default.nix"]
        PKGS_CAP["pkgs/capacities-latest/default.nix"]
        PKGS_CLICKUP["pkgs/clickup-latest/default.nix"]
        PKGS_MORGEN["pkgs/morgen-latest/default.nix"]
        PKGS_OPENCODE["pkgs/opencode-latest/default.nix"]
    end

    %% Host Layer
    subgraph "Hosts"
        HOST_MAC["hosts/Mac124929/default.nix"]
        HOST_MAC_HW["hosts/Mac124929/hardware-configuration.nix"]
        HOST_XPS["hosts/nixos-xps/default.nix"]
        HOST_XPS_HW["hosts/nixos-xps/hardware-configuration.nix"]
        HOST_TSUKI["hosts/tsuki/default.nix"]
        HOST_TSUKI_HW["hosts/tsuki/hardware-configuration.nix"]
        HOST_COMMON_CORE["hosts/common/core/default.nix"]
        HOST_COMMON_OPT["hosts/common/optional/*.nix"]
        HOST_USERS["hosts/common/users/dileep/default.nix"]
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        NIRI["Niri (WM)"]
        HYPR["Hyprland (WM)"]
        WAYBAR["Waybar (Status Bar)"]
        GHOSTTY["Ghostty (Terminal)"]
        KITTY["Kitty (Terminal)"]
        ZSH["Zsh Shell"]
        OMP["Oh-My-Posh"]
        WALKER["Walker Launcher"]
        CAT["Catppuccin Theme"]
        MONA["Monaspace Font"]
        NVIM["Neovim Editor"]
    end

    %% Connections
    FLK_nix -->|imports| NIXOS_MODULES
    FLK_nix -->|imports| HOME_MODULES
    FLK_nix -->|loads| OVERLAYS
    FLK_nix -->|loads| PKGS_DEFAULT

    OVERLAYS -->|customizes| PKGS_DEFAULT
    OVERLAYS -->|customizes| PKGS_CAP
    OVERLAYS -->|customizes| PKGS_CLICKUP
    OVERLAYS -->|customizes| PKGS_MORGEN
    OVERLAYS -->|customizes| PKGS_OPENCODE

    NIXOS_MODULES -->|provided to| HOST_MAC
    HOME_MODULES -->|provided to| HOST_MAC
    OVERLAYS -->|provided to| HOST_MAC
    CORE_COMMON -->|provided to| HOST_MAC
    OPTIONAL_COMMON -->|provided to| HOST_MAC

    NIXOS_MODULES -->|provided to| HOST_XPS
    HOME_MODULES -->|provided to| HOST_XPS
    OVERLAYS -->|provided to| HOST_XPS
    CORE_COMMON -->|provided to| HOST_XPS
    OPTIONAL_COMMON -->|provided to| HOST_XPS

    NIXOS_MODULES -->|provided to| HOST_TSUKI
    HOME_MODULES -->|provided to| HOST_TSUKI
    OVERLAYS -->|provided to| HOST_TSUKI
    CORE_COMMON -->|provided to| HOST_TSUKI
    OPTIONAL_COMMON -->|provided to| HOST_TSUKI

    HOST_MAC -->|deploys| NIRI
    HOST_MAC -->|deploys| HYPR
    HOST_MAC -->|deploys| WAYBAR
    HOST_MAC -->|deploys| GHOSTTY
    HOST_MAC -->|deploys| KITTY
    HOST_MAC -->|deploys| ZSH
    HOST_MAC -->|deploys| OMP
    HOST_MAC -->|deploys| WALKER
    HOST_MAC -->|deploys| CAT
    HOST_MAC -->|deploys| MONA
    HOST_MAC -->|deploys| NVIM

    HOST_XPS -->|deploys| NIRI
    HOST_XPS -->|deploys| HYPR
    HOST_XPS -->|deploys| WAYBAR
    HOST_XPS -->|deploys| GHOSTTY
    HOST_XPS -->|deploys| KITTY
    HOST_XPS -->|deploys| ZSH
    HOST_XPS -->|deploys| OMP
    HOST_XPS -->|deploys| WALKER
    HOST_XPS -->|deploys| CAT
    HOST_XPS -->|deploys| MONA
    HOST_XPS -->|deploys| NVIM

    HOST_TSUKI -->|deploys| NIRI
    HOST_TSUKI -->|deploys| HYPR
    HOST_TSUKI -->|deploys| WAYBAR
    HOST_TSUKI -->|deploys| GHOSTTY
    HOST_TSUKI -->|deploys| KITTY
    HOST_TSUKI -->|deploys| ZSH
    HOST_TSUKI -->|deploys| OMP
    HOST_TSUKI -->|deploys| WALKER
    HOST_TSUKI -->|deploys| CAT
    HOST_TSUKI -->|deploys| MONA
    HOST_TSUKI -->|deploys| NVIM

    %% Click Events
    click FLK_nix "https://github.com/jeremiealcaraz/nixos-config/blob/main//flake.nix"
    click FLK_lock "https://github.com/jeremiealcaraz/nixos-config/blob/main//flake.lock"
    click SHNIX "https://github.com/jeremiealcaraz/nixos-config/blob/main//shell.nix"
    click JUST "https://github.com/jeremiealcaraz/nixos-config/tree/main//justfile"
    click NIXOS_MODULES "https://github.com/jeremiealcaraz/nixos-config/blob/main//modules/nixos/default.nix"
    click HOME_MODULES "https://github.com/jeremiealcaraz/nixos-config/blob/main//modules/home-manager/default.nix"
    click CORE_COMMON "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/core/default.nix"
    click OPTIONAL_COMMON "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/default.nix"
    click OVERLAYS "https://github.com/jeremiealcaraz/nixos-config/blob/main//overlays/default.nix"
    click PKGS_DEFAULT "https://github.com/jeremiealcaraz/nixos-config/blob/main//pkgs/default.nix"
    click PKGS_CAP "https://github.com/jeremiealcaraz/nixos-config/blob/main//pkgs/capacities-latest/default.nix"
    click PKGS_CLICKUP "https://github.com/jeremiealcaraz/nixos-config/blob/main//pkgs/clickup-latest/default.nix"
    click PKGS_MORGEN "https://github.com/jeremiealcaraz/nixos-config/blob/main//pkgs/morgen-latest/default.nix"
    click PKGS_OPENCODE "https://github.com/jeremiealcaraz/nixos-config/blob/main//pkgs/opencode-latest/default.nix"
    click HOST_MAC "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/Mac124929/default.nix"
    click HOST_MAC_HW "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/Mac124929/hardware-configuration.nix"
    click HOST_XPS "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/nixos-xps/default.nix"
    click HOST_XPS_HW "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/nixos-xps/hardware-configuration.nix"
    click HOST_TSUKI "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/tsuki/default.nix"
    click HOST_TSUKI_HW "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/tsuki/hardware-configuration.nix"
    click HOST_COMMON_CORE "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/common/core/default.nix"
    click HOST_COMMON_OPT "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/common/optional/*.nix"
    click HOST_USERS "https://github.com/jeremiealcaraz/nixos-config/blob/main//hosts/common/users/dileep/default.nix"
    click NIRI "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/desktops/niri/default.nix"
    click HYPR "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/desktops/hyprland/default.nix"
    click WAYBAR "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/desktops/waybar/default.nix"
    click GHOSTTY "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/apps/ghostty/default.nix"
    click KITTY "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/apps/kitty/default.nix"
    click ZSH "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/core/shells/zsh.nix"
    click OMP "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/core/cli/oh-my-posh/default.nix"
    click WALKER "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/optional/apps/walker/default.nix"
    click CAT "https://github.com/jeremiealcaraz/nixos-config/tree/main//home/common/core/apps/zathura/catppuccin-mocha"
    click MONA "https://github.com/jeremiealcaraz/nixos-config/blob/main//home/common/core/fonts.nix"

    %% Styles
    classDef infra fill:#9ecae1,stroke:#333,stroke-width:1px
    classDef pkg fill:#a1d99b,stroke:#333,stroke-width:1px
    classDef host fill:#fa9fb5,stroke:#333,stroke-width:1px
    classDef runtime fill:#bcbddc,stroke:#333,stroke-width:1px

    class FLK_nix,FLK_lock,SHNIX,JUST,NIXOS_MODULES,HOME_MODULES,CORE_COMMON,OPTIONAL_COMMON infra
    class OVERLAYS,PKGS_DEFAULT,PKGS_CAP,PKGS_CLICKUP,PKGS_MORGEN,PKGS_OPENCODE pkg
    class HOST_MAC,HOST_MAC_HW,HOST_XPS,HOST_XPS_HW,HOST_TSUKI,HOST_TSUKI_HW,HOST_COMMON_CORE,HOST_COMMON_OPT,HOST_USERS host
    class NIRI,HYPR,WAYBAR,GHOSTTY,KITTY,ZSH,OMP,WALKER,CAT,MONA,NVIM runtime
```
