# elliebytes/burrow architecture

> Architecture diagram of the GitHub repository elliebytes/burrow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elliebytes/burrow
- Repository: https://github.com/elliebytes/burrow

## Overview

Burrow is a Nix-flake auto-discovery framework. Its documented workflow crawls search paths for buildable objects and metadata, then builders turn discovered inputs into flake outputs; metadata is evaluated with builder-defined modules to customize objects. The tree also shows builder implementations for NixOS, Darwin, home configurations, packages, and other modules. Source excerpts were unavailable, so edges below are limited to relationships stated in the README; implementation details and links among builder variants are not inferred.

Main entry points: [`lib/types/builder.nix`](https://github.com/elliebytes/burrow/blob/main/lib/types/builder.nix) (Builder API), [`lib/discover.nix`](https://github.com/elliebytes/burrow/blob/main/lib/discover.nix) (Discovery function), [`parts/builders/modules/modules/default.nix`](https://github.com/elliebytes/burrow/blob/main/parts/builders/modules/modules/default.nix) (Builder modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery and metadata"]
  node_discovery_fn["Discovery function<br/>[discover.nix]"]
  node_object_meta["Object metadata"]
end

subgraph group_builder_api["Builder framework"]
  node_builder_api["Builder API<br/>[builder.nix]"]
  node_builder_modules["Builder modules<br/>[default.nix]"]
end

subgraph group_builder_types["Builder implementations"]
  node_nixos_builder["NixOS builder<br/>[default.nix]"]
  node_darwin_builder["Darwin builder<br/>[default.nix]"]
  node_home_builder["Home builder<br/>[default.nix]"]
  node_package_builder["Package builder<br/>[default.nix]"]
  node_templates["Templates<br/>[templates.nix]"]
  node_overlays["Overlays<br/>[overlays.nix]"]
end

node_maintainer(("Flake maintainer"))
node_search_paths["Search paths"]
node_flake_outputs["Flake outputs"]

node_maintainer -->|"provides"| node_search_paths
node_discovery_fn -->|"crawls"| node_search_paths
node_discovery_fn -->|"evaluates metadata"| node_object_meta
node_builder_api -->|"uses by default"| node_discovery_fn
node_builder_api -->|"customizes objects"| node_object_meta
node_builder_api -->|"defines modules"| node_builder_modules
node_builder_api -->|"builds"| node_flake_outputs

click node_discovery_fn "https://github.com/elliebytes/burrow/blob/main/lib/discover.nix"
click node_builder_api "https://github.com/elliebytes/burrow/blob/main/lib/types/builder.nix"
click node_builder_modules "https://github.com/elliebytes/burrow/blob/main/parts/builders/modules/modules/default.nix"
click node_nixos_builder "https://github.com/elliebytes/burrow/blob/main/parts/builders/nixos/default.nix"
click node_darwin_builder "https://github.com/elliebytes/burrow/blob/main/parts/builders/darwin/default.nix"
click node_home_builder "https://github.com/elliebytes/burrow/blob/main/parts/builders/home/default.nix"
click node_package_builder "https://github.com/elliebytes/burrow/blob/main/parts/builders/packages/default.nix"
click node_templates "https://github.com/elliebytes/burrow/blob/main/parts/builders/templates.nix"
click node_overlays "https://github.com/elliebytes/burrow/blob/main/parts/builders/overlays.nix"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_discovery_fn,node_object_meta toneBlue
class node_builder_api,node_builder_modules toneAmber
class node_nixos_builder,node_darwin_builder,node_home_builder,node_package_builder,node_templates,node_overlays toneMint
class node_maintainer,node_search_paths,node_flake_outputs toneIndigo
```

## Components

### Discovery and metadata

- [Discovery function](https://github.com/elliebytes/burrow/blob/main/lib/discover.nix): `lib/discover.nix`
- **Object metadata**

### Builder framework

- [Builder API](https://github.com/elliebytes/burrow/blob/main/lib/types/builder.nix): `lib/types/builder.nix`
- [Builder modules](https://github.com/elliebytes/burrow/blob/main/parts/builders/modules/modules/default.nix): `parts/builders/modules/modules/default.nix`

### Builder implementations

- [NixOS builder](https://github.com/elliebytes/burrow/blob/main/parts/builders/nixos/default.nix): `parts/builders/nixos/default.nix`
- [Darwin builder](https://github.com/elliebytes/burrow/blob/main/parts/builders/darwin/default.nix): `parts/builders/darwin/default.nix`
- [Home builder](https://github.com/elliebytes/burrow/blob/main/parts/builders/home/default.nix): `parts/builders/home/default.nix`
- [Package builder](https://github.com/elliebytes/burrow/blob/main/parts/builders/packages/default.nix): `parts/builders/packages/default.nix`
- [Templates](https://github.com/elliebytes/burrow/blob/main/parts/builders/templates.nix): `parts/builders/templates.nix`
- [Overlays](https://github.com/elliebytes/burrow/blob/main/parts/builders/overlays.nix): `parts/builders/overlays.nix`

### Other components

- **Flake maintainer**
- **Search paths**
- **Flake outputs**

## Connections

- Flake maintainer → Search paths: provides (evidence: `README.md`)
- Discovery function → Search paths: crawls (evidence: `README.md`)
- Discovery function → Object metadata: evaluates metadata (evidence: `README.md`)
- Builder API → Discovery function: uses by default (evidence: `README.md`)
- Builder API → Object metadata: customizes objects (evidence: `README.md`)
- Builder API → Builder modules: defines modules (evidence: `README.md`)
- Builder API → Flake outputs: builds (evidence: `README.md`)