# theoptimist/systemosaurus architecture

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

- Interactive diagram: https://gitdiagram.com/theoptimist/systemosaurus
- Repository: https://github.com/theoptimist/systemosaurus

## Overview

##### Project Type and Purpose
- Systemosaurus is a *configuration-management* project: it automates the installation and configuration of macOS (Darwin) machines via Nix, Nix-Darwin, Home-Manager, Homebrew and App Store (mas).
- Its goal is to bootstrap a new Mac: install toolchains, clone the repo, apply Nix configurations, and manage user dotfiles.

##### File Structure
Top-level directories reveal the architectural layers:
- config/       → Nix expressions for package installs & system services
- home/         → Home-Manager configurations for user dotfiles & tools
- modules/      → Reusable Nix modules to extend configurations
- profiles/     → Named configuration profiles (groups of settings)
- install       → Bootstrapping script to kick off the process
- Nix files     → configuration.nix, shell.nix, default.nix, platform-specific overrides

##### Extract Key Insights from the README
- The install script triggers:
- Installation of Command Line Tools, Nix, Nix-Darwin
- Invocation of darwin-rebuild to apply `config/` and `modules/`
- Use of Home-Manager (`home/`) for user-level dotfiles
- Fallback on Homebrew and mas for packages not in Nix
- Layers: System (config + modules + profiles), User (home), External (Homebrew, mas).

##### Main Components
a. Bootstrap/Installer Layer
- install script (curl | bash)
- environment checks (CLT, Nix presence)
b. System Configuration Layer
- Nix Daemon & nix-darwin
- config/ directory (default.nix + per-platform overrides)
- modules/ (darwin modules, security modules, etc.)
- profiles/ groupings
c. User Configuration Layer
- Home-Manager (`home/`) with subfolders for shell, terminal, cloud, darwin-specific widgets
- Dotfiles & functions.sh, p10k.zsh, tmux.conf, kitty.conf
d. External Package Managers
- Homebrew
- mas (App Store CLI)
e. Underlying Platform
- macOS (Darwin)
- Unencrypted Nix store volume

##### Relationships and Data Flows
- Installer → Nix Daemon & nix-darwin
- nix-darwin → reads config/ + modules/ + profiles/ → builds /run/current-system
- home-manager → reads home/ → populates $HOME dotfiles & apps
- Both config & home layers may call out to external package managers (brew, mas) when needed
- All layers depend on the underlying macOS host

##### Architectural Patterns and Technologies
- Declarative configuration (Nix expressions)
- Layered approach: System vs. User vs. External
- Reusable modules (DRY) in modules/
- Profile-based grouping for different machine roles
- Imperative bootstrap (install script) transitioning into declarative management

##### Essential Architectural Elements
- Don’t just lump “config/” as a single block—show subdomains: packages, services, platform overrides
- Expose extensibility: where a new module or profile would integrate
- That both system and user layers are ultimately driven by Nix’s evaluation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host macOS (Darwin)" 
        direction TB
        style Host fill:none,stroke:#333,stroke-width:2px

        subgraph "Bootstrap/Installer Layer"
            direction TB
            install["install/ (Installer Script)"]:::bootstrap
        end

        subgraph "System Configuration Layer"
            direction TB
            NixDaemon["Nix Daemon & nix-darwin"]:::system
            configuration["configuration.nix"]:::system
            subgraph "config/"
                direction TB
                cfg_default["default.nix"]:::system
                subgraph "darwin/"
                    direction TB
                    cfg_darwin_default["default.nix"]:::system
                    cfg_homebrew["homebrew.nix"]:::system
                    cfg_preferences["preferences.nix"]:::system
                    cfg_security["security.nix"]:::system
                end
                cfg_fonts["fonts.nix"]:::system
                cfg_docker["docker.nix"]:::system
                cfg_hm["home-manager.nix"]:::system
                cfg_shell["shell.nix"]:::system
                cfg_terminal["terminal.nix"]:::system
                cfg_vscode["vscode.nix"]:::system
            end
            subgraph "modules/"
                direction TB
                mod_default["default.nix"]:::system
                subgraph "darwin/"
                    direction TB
                    mod_darwin_default["default.nix"]:::system
                    mod_darwin_sec["security.nix"]:::system
                end
            end
            profiles["profiles/default.nix"]:::system
        end

        subgraph "User Configuration Layer"
            direction TB
            HomeManager["home/default.nix"]:::user
            subgraph "home/shell/"
                direction TB
                shell_default["default.nix"]:::user
                shell_funcs["functions.sh"]:::user
                shell_p10k["p10k.zsh"]:::user
                shell_tmux["tmux.conf"]:::user
                shell_tmux_local["tmux.conf.local"]:::user
            end
            subgraph "home/terminal/"
                direction TB
                term_default["default.nix"]:::user
                term_kitty["kitty.conf"]:::user
            end
            subgraph "home/cloud/"
                direction TB
                cloud_default["default.nix"]:::user
                cloud_aws["aws.nix"]:::user
                subgraph "oci/"
                    direction TB
                    cloud_oci_default["default.nix"]:::user
                    cloud_oci_funcs["functions.sh"]:::user
                end
            end
            home_git["git.nix"]:::user
            home_lastpass["lastpass.nix"]:::user
            home_oci["oci.nix"]:::user
            home_ssh["ssh.nix"]:::user
            subgraph "home/darwin/ubersicht/widgets"
                direction TB
                widget_date["dateinwords/index.jsx"]:::user
                widget_time["timeinwords/index.jsx"]:::user
            end
        end

        subgraph "External Package Managers"
            direction TB
            Brew["Homebrew"]:::external
            MAS["mas (App Store CLI)"]:::external
        end

        install -->|"bootstrap"| NixDaemon
        NixDaemon -->|"evaluates"| configuration
        configuration --> cfg_default
        configuration --> subgraph_mod[modules]
        cfg_default --> cfg_darwin_default
        cfg_darwin_default --> cfg_homebrew
        cfg_darwin_default --> cfg_preferences
        cfg_darwin_default --> cfg_security
        configuration --> profiles
        subgraph_mod --> mod_default
        subgraph_mod --> mod_darwin_default
        mod_darwin_default --> mod_darwin_sec

        NixDaemon -->|"darwin-rebuild"| Host
        HomeManager -->|"home-manager switch"| HomeManager
        HomeManager --> shell_default
        HomeManager --> term_default
        HomeManager --> cloud_default
        shell_default --> shell_funcs
        shell_default --> shell_p10k
        shell_default --> shell_tmux
        shell_tmux --> shell_tmux_local
        term_default --> term_kitty
        cloud_default --> cloud_aws
        cloud_default --> cloud_oci_default
        cloud_oci_default --> cloud_oci_funcs

        cfg_homebrew -->|brew install| Brew
        cfg_preferences -->|mas install| MAS
        shell_default -->|may call| Brew
        shell_default -->|may call| MAS

    end

    classDef bootstrap fill:#D0E8FF,stroke:#005BAA,color:#005BAA;
    classDef system fill:#E2F5D6,stroke:#2C6E1A,color:#2C6E1A;
    classDef user fill:#FFE5B4,stroke:#CC8400,color:#CC8400;
    classDef external fill:#E0E0E0,stroke:#888888,color:#444444;

    click install "https://github.com/theoptimist/systemosaurus/tree/main/install/"
    click configuration "https://github.com/theoptimist/systemosaurus/blob/main/configuration.nix"
    click cfg_default "https://github.com/theoptimist/systemosaurus/blob/main/config/default.nix"
    click cfg_darwin_default "https://github.com/theoptimist/systemosaurus/blob/main/config/darwin/default.nix"
    click cfg_homebrew "https://github.com/theoptimist/systemosaurus/blob/main/config/darwin/homebrew.nix"
    click cfg_preferences "https://github.com/theoptimist/systemosaurus/blob/main/config/darwin/preferences.nix"
    click cfg_security "https://github.com/theoptimist/systemosaurus/blob/main/config/darwin/security.nix"
    click cfg_fonts "https://github.com/theoptimist/systemosaurus/blob/main/config/fonts.nix"
    click cfg_docker "https://github.com/theoptimist/systemosaurus/blob/main/config/docker.nix"
    click cfg_hm "https://github.com/theoptimist/systemosaurus/blob/main/config/home-manager.nix"
    click cfg_shell "https://github.com/theoptimist/systemosaurus/blob/main/config/shell.nix"
    click cfg_terminal "https://github.com/theoptimist/systemosaurus/blob/main/config/terminal.nix"
    click cfg_vscode "https://github.com/theoptimist/systemosaurus/blob/main/config/vscode.nix"
    click mod_default "https://github.com/theoptimist/systemosaurus/blob/main/modules/default.nix"
    click mod_darwin_default "https://github.com/theoptimist/systemosaurus/blob/main/modules/darwin/default.nix"
    click mod_darwin_sec "https://github.com/theoptimist/systemosaurus/blob/main/modules/darwin/security.nix"
    click profiles "https://github.com/theoptimist/systemosaurus/blob/main/profiles/default.nix"
    click HomeManager "https://github.com/theoptimist/systemosaurus/blob/main/home/default.nix"
    click shell_default "https://github.com/theoptimist/systemosaurus/blob/main/home/shell/default.nix"
    click shell_funcs "https://github.com/theoptimist/systemosaurus/blob/main/home/shell/functions.sh"
    click shell_p10k "https://github.com/theoptimist/systemosaurus/blob/main/home/shell/p10k.zsh"
    click shell_tmux "https://github.com/theoptimist/systemosaurus/blob/main/home/shell/tmux.conf"
    click shell_tmux_local "https://github.com/theoptimist/systemosaurus/blob/main/home/shell/tmux.conf.local"
    click term_default "https://github.com/theoptimist/systemosaurus/blob/main/home/terminal/default.nix"
    click term_kitty "https://github.com/theoptimist/systemosaurus/blob/main/home/terminal/kitty.conf"
    click cloud_default "https://github.com/theoptimist/systemosaurus/blob/main/home/cloud/default.nix"
    click cloud_aws "https://github.com/theoptimist/systemosaurus/blob/main/home/cloud/aws.nix"
    click cloud_oci_default "https://github.com/theoptimist/systemosaurus/blob/main/home/cloud/oci/default.nix"
    click cloud_oci_funcs "https://github.com/theoptimist/systemosaurus/blob/main/home/cloud/oci/functions.sh"
    click home_git "https://github.com/theoptimist/systemosaurus/blob/main/home/git.nix"
    click home_lastpass "https://github.com/theoptimist/systemosaurus/blob/main/home/lastpass.nix"
    click home_oci "https://github.com/theoptimist/systemosaurus/blob/main/home/oci.nix"
    click home_ssh "https://github.com/theoptimist/systemosaurus/blob/main/home/ssh.nix"
    click widget_date "https://github.com/theoptimist/systemosaurus/blob/main/home/darwin/ubersicht/widgets/dateinwords/index.jsx"
    click widget_time "https://github.com/theoptimist/systemosaurus/blob/main/home/darwin/ubersicht/widgets/timeinwords/index.jsx"
```
