How serpentian/alfheimos works
Project Type and Purpose
• This is a modular NixOS “dotfiles” repository built around Nix Flakes and Home Manager.
• Purpose: orchestrate system-level and user-level configuration for multiple profiles (desktop, laptop, work), provide custom packages and overlays, and include a standalone “ags” TypeScript UI plugin for the Hyprland window manager.
Top-Level Architecture
• Flake (flake.nix + flake.lock)
• Acts as the root orchestrator.
• Exposes inputs: nixpkgs, home-manager, and custom overlays.
• Defines profiles via a profile variable.
• Overlays (lib/overlays.nix + overlays/)
• Custom modifications to nixpkgs.
• Custom Packages (pkgs/)
• Additional package definitions and patches.
• Secrets (secrets/default.yaml)
• Secure parameter store, consumed by modules where needed.
Profile Layer
• Directory: profiles/
• Each profile (desktop, laptop, work) contains:
• system/configuration.nix – NixOS system modules import.
• system/hardware-configuration.nix – auto-generated hardware config.
• home.nix – Home Manager user modules import.
• The Flake’s profile variable selects which profile’s configuration.nix and home.nix to build.
System Modules Layer
• Directory: system/
• Organized by concern: apps/, gaming/, hardware/, security/, wm/
• Each .nix file or subdirectory exports NixOS modules that get imported into configuration.nix.
• Example: system/wm/hyprland.nix configures the Hyprland compositor.
User (Home Manager) Modules Layer
• Directory: user/
• Organized by concern: apps/, browsers/, editors/, gaming/, shells/, wm/
• Each subfolder contains Home Manager Nix modules for user-level configuration.
• Example: user/wm/hyprland/ags.nix references the non-nix/ags plugin.
Shell Environments
• Directory: shells/
• Contains Nix Flakes to spin up project-specific development shells (python, tarantool, etc.).
Themes & Assets
• assets/ – screenshots and theme previews.
Non-Nix Standalone Plugin (“ags”)
• Directory: non-nix/ags
• A TypeScript project providing UI widgets and services for Hyprland.
• Key subcomponents:
• greeter/ – session, statusbar, auth services
• service/ – background utilities (brightness, weather, wallpaper)
• widget/ – UI widget classes (bar, notifications, overview)
• style/ – SCSS and style.ts theming
• main.ts – entry point for the AGS process
Component Relationships & Data Flow
• Flake
↳ imports Overlays + Custom Packages
↳ selects Profile
• Profile
↳ imports System Modules → generates NixOS system build
↳ imports Home Modules → generates Home Manager build
• System Modules
↳ may reference Custom Packages from pkgs/ or assets/themes
↳ invoke secrets via sops or Home Manager secrets
• Home Modules
↳ include app, shell, editor and WM settings
↳ pull in the “ags” plugin via the user/wm/hyprland/ags.nix module
• “ags” Plugin
↳ Compiled/installed by system or home modules
↳ Runs as a user process under Hyprland, communicating with Hyprland via IPC
Architectural Patterns & Principles
• Layered modularity: Flake → Profiles → System/Home modules → Custom overlays
• Single source of truth: flake.nix as entry point
• Separation of concerns: system vs. user config; generic modules vs. profile-specific
• Extensibility: add new profiles, modules, overlays without changing core Flake
Technologies & Frameworks
• Nix / NixOS / Nix Flakes / Home Manager
• TypeScript / Node.js (for the AGS plugin)
• SCSS for styling AGS widgets
• Hyprland window manager on Wayland