# aka-raccoon/.factory architecture

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

- Interactive diagram: https://gitdiagram.com/aka-raccoon/.factory
- Repository: https://github.com/aka-raccoon/.factory

## Overview

##### Main Components
a. Configuration Layers:
– Hosts: Under the “hosts” directory you see groupings (e.g., hosts/amb, hosts/asc, hosts/cmb, hosts/ley, hosts/pmb) and a _modules subdirectory that further encapsulates host‐specific configuration including NixOS modules, common defaults, filesystem setups, and services (DNS, k3s, nginx, etc).
– Homes: The “homes” directory contains home-manager configurations for different users (such as I572068, c4300n, trash-panda-v91-beta) as well as a shared modules folder (“homes/_modules”) that covers domains like browsers, deployment, editor configurations, shells, themes, virtualization, etc.
b. Package and Overlay Management:
– Pkgs: The “pkgs” directory holds custom package definitions and related TypeScript code (for example, the karabiner-config subdirectory) that likely provide further customization or installation routines.
– Overlays and Lib: The “overlays” directory (and “lib/mkSystem.nix”) indicate additional customization layers that override or extend standard Nixpkgs behavior.
c. Core Nix Infrastructure:
– flake.nix, flake.lock, and Taskfile.yaml files at the project root (and in the .taskfiles subfolders) show that the project uses flakes and task automation scripts. These serve as the entry-points for building, testing, or deploying the configurations.
d. Auxiliary Components:
– The presence of .github related items, along with organizational directories like .taskfiles for different domains (nix, sops), indicates integration with CI/CD systems and secrets management.

##### Relationships and Interactions
- How the base Nix infrastructure (flake.nix, Taskfile.yaml) feeds into building both hosts and homes configurations.
- The interaction between shared modules (in both hosts/_modules and homes/_modules) and their specific instances in individual hosts or user configuration directories.
- How overlays and pkgs provide modifications or extensions to base Nixpkgs which then are consumed by the hosts and homes modules.
- External interactions such as integration with secrets management tools (sops in .taskfiles/sops) and potential CI/CD pipelines (via the .github directory).

##### Architectural Patterns and Design Principles
- Modularity: The repository uses a highly modular structure (separation of concerns between host configuration, user home configuration, package customization, and overlays).
- Reusability: Notice common modules reused across different hosts and homes.
- Declarative configuration: The project is built around a declarative model where system settings are fully represented by Nix expressions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Core Infrastructure
    subgraph "Layer 1: Core Infrastructure"
        FN("Flake"):::core
        FL("Lock"):::core
        TF("Taskfile"):::core
        TFIL("Taskfiles"):::core
    end

    %% Layer 1: CI/CD Automation
    subgraph "Layer 1: CI/CD Automation"
        GH("GitHub"):::cd
        TSOPS("SOPS"):::cd
    end

    %% Layer 2: Customization Modules
    subgraph "Layer 2: Customization Modules"
        subgraph "Package Customizations"
            PK("Pkgs"):::cust
            KAR("Karabiner"):::cust
        end
        subgraph "Overlay Customizations"
            OV("Overlays"):::cust
            MK("mkSystem"):::cust
        end
    end

    %% Layer 3: Configurations
    subgraph "Layer 3: Configurations"
        subgraph "Host Configurations"
            H("Hosts"):::config
            HM("Host Modules"):::config
        end
        subgraph "Home/User Configurations"
            HOME("Homes"):::config
            HOMEM("Home Modules"):::config
        end
    end

    %% Connections from Core Infrastructure to Configurations and Customization Modules
    FN -->|"feeds"| H
    FN -->|"feeds"| HOME
    FN -->|"supports"| PK
    FN -->|"supports"| OV

    %% Connections from Customization Modules to Configurations
    PK -->|"customizes"| H
    PK -->|"customizes"| HOME
    KAR -->|"customizes"| H
    KAR -->|"customizes"| HOME
    OV -->|"overrides"| H
    OV -->|"overrides"| HOME
    MK -->|"overrides"| H
    MK -->|"overrides"| HOME

    %% Additional feeds from Core Infrastructure to module sub-components
    FN -->|"feeds"| HM
    FN -->|"feeds"| HOMEM

    %% CI/CD Automation influence on Core Infrastructure
    GH -->|"triggers"| FN
    TSOPS -->|"secures"| TFIL

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef cust fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef cd fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events for Core Infrastructure
    click FN "https://github.com/aka-raccoon/.factory/blob/main/flake.nix"
    click FL "https://github.com/aka-raccoon/.factory/blob/main/flake.lock"
    click TF "https://github.com/aka-raccoon/.factory/blob/main/Taskfile.yaml"
    click TFIL "https://github.com/aka-raccoon/.factory/tree/main/.taskfiles/"

    %% Click Events for CI/CD Automation
    click GH "https://github.com/aka-raccoon/.factory/tree/main/.github/"
    click TSOPS "https://github.com/aka-raccoon/.factory/tree/main/.taskfiles/sops/"

    %% Click Events for Host Configurations
    click H "https://github.com/aka-raccoon/.factory/tree/main/hosts/"
    click HM "https://github.com/aka-raccoon/.factory/tree/main/hosts/_modules/"

    %% Click Events for Home/User Configurations
    click HOME "https://github.com/aka-raccoon/.factory/tree/main/homes/"
    click HOMEM "https://github.com/aka-raccoon/.factory/tree/main/homes/_modules/"

    %% Click Events for Package Customizations
    click PK "https://github.com/aka-raccoon/.factory/tree/main/pkgs/"
    click KAR "https://github.com/aka-raccoon/.factory/tree/main/pkgs/karabiner-config/"

    %% Click Events for Overlay Customizations
    click OV "https://github.com/aka-raccoon/.factory/tree/main/overlays/"
    click MK "https://github.com/aka-raccoon/.factory/blob/main/lib/mkSystem.nix"
```
