# julienbardi/homelab architecture

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

- Interactive diagram: https://gitdiagram.com/julienbardi/homelab
- Repository: https://github.com/julienbardi/homelab

## Overview

This repository is the operational control plane for a homelab spanning a Ugreen NAS and ASUS router. The principal operator workflow is to work from the documented contracts and Make targets, then apply configuration and host/router automation to converge network and services. Major branches include WireGuard, DNS, firewall/routing, certificates, tailnet access, and monitoring. The README describes these capabilities at a high level; the supplied source excerpts cover only peripheral icon tools and DNS warming, so subsystem links not established there are marked unverified.

Main entry points: [`mk/01_core.mk`](https://github.com/julienbardi/homelab/blob/main/mk/01_core.mk) (Make control plane), [`router/jffs/scripts/homelab-router-provision.sh`](https://github.com/julienbardi/homelab/blob/main/router/jffs/scripts/homelab-router-provision.sh) (Router automation), [`mk/40_nas-caddy.mk`](https://github.com/julienbardi/homelab/blob/main/mk/40_nas-caddy.mk) (NAS service exposure), [`mk/wireguard/30_generate.mk`](https://github.com/julienbardi/homelab/blob/main/mk/wireguard/30_generate.mk) (WireGuard lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator workflow"]
  node_contracts["Architecture contracts<br/>[contracts.md]"]
  node_make["Make control plane<br/>[01_core.mk]"]
end

subgraph group_network["Network control"]
  node_wireguard["WireGuard lifecycle<br/>[30_generate.mk]"]
  node_wg_inputs["WireGuard inventory<br/>[hosts.tsv]"]
  node_routing["Routing convergence"]
  node_firewall["Firewall rules"]
  node_router["Router automation"]
end

subgraph group_services["Service operations"]
  node_dns["DNS services<br/>[60_unbound.mk]"]
  node_dns_config["DNS configuration<br/>[unbound.conf]"]
  node_certificates["Certificate lifecycle<br/>[acme-issue.sh]"]
  node_tailnet["Tailnet access<br/>[81_headscale.mk]"]
  node_monitoring["Monitoring<br/>[prometheus.yml]"]
  node_nas_services["NAS service exposure<br/>[40_nas-caddy.mk]"]
end

subgraph group_platform["Host and router"]
  node_host_config["Host configuration"]
end

node_operator(("Homelab operator"))
node_router_device["ASUS router"]
node_nas_device["Ugreen NAS"]

node_operator -.->|"consults"| node_contracts
node_operator -.->|"operates"| node_make
node_make -.->|"dispatches"| node_wireguard
node_wg_inputs -.->|"supplies inventory"| node_wireguard
node_make -.->|"dispatches"| node_routing
node_make -.->|"dispatches"| node_firewall
node_make -.->|"dispatches"| node_router
node_make -.->|"dispatches"| node_dns
node_dns_config -.->|"configures"| node_dns
node_make -.->|"dispatches"| node_certificates
node_make -.->|"dispatches"| node_tailnet
node_make -.->|"configures"| node_monitoring
node_make -.->|"dispatches"| node_nas_services
node_make -.->|"installs"| node_host_config
node_router -.->|"configures"| node_router_device
node_nas_services -.->|"configures"| node_nas_device

click node_contracts "https://github.com/julienbardi/homelab/blob/main/contracts.md"
click node_make "https://github.com/julienbardi/homelab/blob/main/mk/01_core.mk"
click node_wireguard "https://github.com/julienbardi/homelab/blob/main/mk/wireguard/30_generate.mk"
click node_wg_inputs "https://github.com/julienbardi/homelab/blob/main/wireguard/input/hosts.tsv"
click node_routing "https://github.com/julienbardi/homelab/blob/main/scripts/homelab-prefix-converge.sh"
click node_firewall "https://github.com/julienbardi/homelab/blob/main/scripts/homelab-nft-apply.sh"
click node_router "https://github.com/julienbardi/homelab/blob/main/router/jffs/scripts/homelab-router-provision.sh"
click node_dns "https://github.com/julienbardi/homelab/blob/main/mk/60_unbound.mk"
click node_dns_config "https://github.com/julienbardi/homelab/blob/main/config/unbound/unbound.conf"
click node_certificates "https://github.com/julienbardi/homelab/blob/main/scripts/acme-issue.sh"
click node_tailnet "https://github.com/julienbardi/homelab/blob/main/mk/81_headscale.mk"
click node_monitoring "https://github.com/julienbardi/homelab/blob/main/config/prometheus/prometheus.yml"
click node_nas_services "https://github.com/julienbardi/homelab/blob/main/mk/40_nas-caddy.mk"
click node_host_config "https://github.com/julienbardi/homelab/tree/main/config/systemd"

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_contracts,node_make toneBlue
class node_wireguard,node_wg_inputs,node_routing,node_firewall,node_router toneAmber
class node_dns,node_dns_config,node_certificates,node_tailnet,node_monitoring,node_nas_services,node_router_device toneMint
class node_host_config toneRose
class node_operator,node_nas_device toneIndigo
```

## Components

### Operator workflow

- [Architecture contracts](https://github.com/julienbardi/homelab/blob/main/contracts.md): `contracts.md`
- [Make control plane](https://github.com/julienbardi/homelab/blob/main/mk/01_core.mk): `mk/01_core.mk`

### Network control

- [WireGuard lifecycle](https://github.com/julienbardi/homelab/blob/main/mk/wireguard/30_generate.mk): `mk/wireguard/30_generate.mk`
- [WireGuard inventory](https://github.com/julienbardi/homelab/blob/main/wireguard/input/hosts.tsv): `wireguard/input/hosts.tsv`
- [Routing convergence](https://github.com/julienbardi/homelab/blob/main/scripts/homelab-prefix-converge.sh): `scripts/homelab-prefix-converge.sh`
- [Firewall rules](https://github.com/julienbardi/homelab/blob/main/scripts/homelab-nft-apply.sh): `scripts/homelab-nft-apply.sh`
- [Router automation](https://github.com/julienbardi/homelab/blob/main/router/jffs/scripts/homelab-router-provision.sh): `router/jffs/scripts/homelab-router-provision.sh`

### Service operations

- [DNS services](https://github.com/julienbardi/homelab/blob/main/mk/60_unbound.mk): `mk/60_unbound.mk`
- [DNS configuration](https://github.com/julienbardi/homelab/blob/main/config/unbound/unbound.conf): `config/unbound/unbound.conf`
- [Certificate lifecycle](https://github.com/julienbardi/homelab/blob/main/scripts/acme-issue.sh): `scripts/acme-issue.sh`
- [Tailnet access](https://github.com/julienbardi/homelab/blob/main/mk/81_headscale.mk): `mk/81_headscale.mk`
- [Monitoring](https://github.com/julienbardi/homelab/blob/main/config/prometheus/prometheus.yml): `config/prometheus/prometheus.yml`
- [NAS service exposure](https://github.com/julienbardi/homelab/blob/main/mk/40_nas-caddy.mk): `mk/40_nas-caddy.mk`

### Host and router

- [Host configuration](https://github.com/julienbardi/homelab/tree/main/config/systemd): `config/systemd`

### Other components

- **Homelab operator**
- **ASUS router**
- **Ugreen NAS**

## Connections

- Homelab operator → Architecture contracts: consults (evidence: `README.md`)
- Homelab operator → Make control plane: operates (evidence: `README.md`)
- Make control plane → WireGuard lifecycle: dispatches
- WireGuard inventory → WireGuard lifecycle: supplies inventory
- Make control plane → Routing convergence: dispatches
- Make control plane → Firewall rules: dispatches
- Make control plane → Router automation: dispatches
- Make control plane → DNS services: dispatches
- DNS configuration → DNS services: configures
- Make control plane → Certificate lifecycle: dispatches
- Make control plane → Tailnet access: dispatches
- Make control plane → Monitoring: configures
- Make control plane → NAS service exposure: dispatches
- Make control plane → Host configuration: installs
- Router automation → ASUS router: configures
- NAS service exposure → Ugreen NAS: configures