How jeremiealcaraz/nixos-config works
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.