# serpentian/alfheimos architecture

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

- Interactive diagram: https://gitdiagram.com/serpentian/alfheimos
- Repository: https://github.com/serpentian/alfheimos

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flake Orchestrator
    Flake["Flake Orchestrator"]:::flake
    Flake -->|"imports"| Overlays
    Flake -->|"imports"| CustomPkgs
    Flake -->|"imports"| Secrets
    Flake -->|"selects profile"| ProfileSelector

    %% Inputs
    Overlays["Overlays"]:::flake
    CustomPkgs["Custom Packages"]:::flake
    Secrets["Secrets Store"]:::external

    ProfileSelector["Profile Selector"]:::profile

    %% Profiles
    subgraph "Profiles" 
        direction TB
        Desktop["Desktop Profile"]:::profile
        Laptop["Laptop Profile"]:::profile
        Work["Work Profile"]:::profile
    end

    ProfileSelector -->|"desktop"| Desktop
    ProfileSelector -->|"laptop"| Laptop
    ProfileSelector -->|"work"| Work

    %% Desktop Profile Modules
    subgraph "Desktop Profile Modules" 
        direction TB
        DSys["System Modules"]:::system
        DHome["Home Modules"]:::home
    end
    Desktop --> DSys
    Desktop --> DHome

    %% Laptop Profile Modules
    subgraph "Laptop Profile Modules" 
        direction TB
        LSys["System Modules"]:::system
        LHome["Home Modules"]:::home
    end
    Laptop --> LSys
    Laptop --> LHome

    %% Work Profile Modules
    subgraph "Work Profile Modules" 
        direction TB
        WSys["System Modules"]:::system
        WHome["Home Modules"]:::home
    end
    Work --> WSys
    Work --> WHome

    %% System Modules Detail
    subgraph "System Modules Layer" 
        direction TB
        SysApps["system/apps"]:::system
        SysGaming["system/gaming"]:::system
        SysHardware["system/hardware"]:::system
        SysSecurity["system/security"]:::system
        SysWM["system/wm"]:::system
    end

    DSys --> SysApps
    DSys --> SysGaming
    DSys --> SysHardware
    DSys --> SysSecurity
    DSys --> SysWM

    LSys --> SysApps
    LSys --> SysGaming
    LSys --> SysHardware
    LSys --> SysSecurity
    LSys --> SysWM

    WSys --> SysApps
    WSys --> SysGaming
    WSys --> SysHardware
    WSys --> SysSecurity
    WSys --> SysWM

    %% Home Modules Detail
    subgraph "Home Modules Layer"
        direction TB
        HomeApps["user/apps"]:::home
        HomeBrowsers["user/browsers"]:::home
        HomeEditors["user/editors"]:::home
        HomeGaming["user/gaming"]:::home
        HomeShells["user/shells"]:::home
        HomeWM["user/wm"]:::home
    end

    DHome --> HomeApps
    DHome --> HomeBrowsers
    DHome --> HomeEditors
    DHome --> HomeGaming
    DHome --> HomeShells
    DHome --> HomeWM

    LHome --> HomeApps
    LHome --> HomeBrowsers
    LHome --> HomeEditors
    LHome --> HomeGaming
    LHome --> HomeShells
    LHome --> HomeWM

    WHome --> HomeApps
    WHome --> HomeBrowsers
    WHome --> HomeEditors
    WHome --> HomeGaming
    WHome --> HomeShells
    WHome --> HomeWM

    %% AGS Plugin
    AGS["AGS Plugin"]:::plugin
    HomeWM -->|"pulls in"| HyprlandMod
    HyprlandMod["user/wm/hyprland"]:::home -->|"loads ags"| AGS

    %% Support Layers
    Shells["Shell Environments"]:::external
    Themes["Themes & Assets"]:::external

    Shells --> SysApps
    Shells --> HomeShells
    Themes --> SysApps
    Themes --> HomeApps

    %% Custom Packages and Overlays to System Modules
    CustomPkgs -->|"used by"| SysApps
    Overlays -->|"modify"| SysHardware

    %% Secrets usage
    Secrets -->|"invoked by"| SysSecurity
    Secrets -->|"invoked by"| HomeApps

    %% Click Events
    click Flake "https://github.com/serpentian/alfheimos/blob/master/flake.nix"
    click Overlays "https://github.com/serpentian/alfheimos/blob/master/lib/overlays.nix"
    click Overlays "https://github.com/serpentian/alfheimos/blob/master/overlays/default.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/default.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/hydra.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/nemu.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/neonmodem.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/stmp.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/blob/master/pkgs/subsonic-tui.nix"
    click CustomPkgs "https://github.com/serpentian/alfheimos/tree/master/pkgs/patches/"
    click Secrets "https://github.com/serpentian/alfheimos/blob/master/secrets/default.yaml"
    click Desktop "https://github.com/serpentian/alfheimos/blob/master/profiles/desktop/configuration.nix"
    click Desktop "https://github.com/serpentian/alfheimos/blob/master/profiles/desktop/hardware-configuration.nix"
    click Desktop "https://github.com/serpentian/alfheimos/blob/master/profiles/desktop/home.nix"
    click Laptop "https://github.com/serpentian/alfheimos/blob/master/profiles/laptop/configuration.nix"
    click Laptop "https://github.com/serpentian/alfheimos/blob/master/profiles/laptop/hardware-configuration.nix"
    click Laptop "https://github.com/serpentian/alfheimos/blob/master/profiles/laptop/home.nix"
    click Work "https://github.com/serpentian/alfheimos/blob/master/profiles/work/configuration.nix"
    click Work "https://github.com/serpentian/alfheimos/blob/master/profiles/work/hardware-configuration.nix"
    click Work "https://github.com/serpentian/alfheimos/blob/master/profiles/work/home.nix"
    click SysApps "https://github.com/serpentian/alfheimos/tree/master/system/apps/"
    click SysGaming "https://github.com/serpentian/alfheimos/tree/master/system/gaming/"
    click SysHardware "https://github.com/serpentian/alfheimos/tree/master/system/hardware/"
    click SysSecurity "https://github.com/serpentian/alfheimos/tree/master/system/security/"
    click SysWM "https://github.com/serpentian/alfheimos/blob/master/system/wm/hyprland.nix"
    click HomeApps "https://github.com/serpentian/alfheimos/tree/master/user/apps/"
    click HomeBrowsers "https://github.com/serpentian/alfheimos/tree/master/user/browsers/"
    click HomeEditors "https://github.com/serpentian/alfheimos/tree/master/user/editors/neovim/"
    click HomeGaming "https://github.com/serpentian/alfheimos/tree/master/user/gaming/"
    click HomeShells "https://github.com/serpentian/alfheimos/tree/master/user/shells/"
    click HomeWM "https://github.com/serpentian/alfheimos/blob/master/user/wm/hyprland/ags.nix"
    click Shells "https://github.com/serpentian/alfheimos/blob/master/shells/python/flake.nix"
    click Shells "https://github.com/serpentian/alfheimos/blob/master/shells/tarantool/flake.nix"
    click Shells "https://github.com/serpentian/alfheimos/blob/master/shells/comfy/flake.nix"
    click Shells "https://github.com/serpentian/alfheimos/blob/master/shells/invoke/flake.nix"
    click Shells "https://github.com/serpentian/alfheimos/blob/master/shells/lampray/flake.nix"
    click Themes "https://github.com/serpentian/alfheimos/tree/master/assets/"
    click Themes "https://github.com/serpentian/alfheimos/tree/master/themes/"
    click AGS "https://github.com/serpentian/alfheimos/blob/master/non-nix/ags/main.ts"

    %% Styles
    classDef flake fill:#dae8fc,stroke:#6c8ebf,color:#073763
    classDef profile fill:#e1f5a9,stroke:#7aa122,color:#40540d
    classDef system fill:#ffe6cc,stroke:#d99002,color:#663e00
    classDef home fill:#fff4b2,stroke:#d4a200,color:#665000
    classDef plugin fill:#f4dcff,stroke:#a75fcc,color:#4b0d3f
    classDef external fill:#f0f0f0,stroke:#999999,color:#333333
```
