# nixknight/home-ops architecture

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

- Interactive diagram: https://gitdiagram.com/nixknight/home-ops
- Repository: https://github.com/nixknight/home-ops

## Overview

##### Project type and purpose
- This is an “Infrastructure-as-Code” and “Configuration-as-Code” repository for home-lab automation, renamed “Home-Ops.”
- It combines Terraform/Terragrunt (for VM provisioning on Proxmox), Ansible (for OS and service configuration), Docker (for service containers), and CI/CD workflows (to build container images).

##### File structure
- Top-level folders:
- ansible – roles, playbooks, inventories, extravars, templates
- docker – Dockerfiles and helper scripts for Kea DHCP and PowerDNS
- terragrunt – HCL modules and configs to spin up VMs on Proxmox
- .github/workflows – CI workflows to build container images
- utils – helper scripts (e.g., vault decryptor)
- Key patterns:
- Infrastructure provisioning (terragrunt) → VM hosts on Proxmox
- Configuration management (Ansible playbooks & roles)
- Container build pipeline (GitHub Actions)
- Service decomposition: DHCP (Kea), DNS (PowerDNS), Pi-hole, authentik SSO, monitoring stack (Prometheus, Grafana, Telegraf), NGINX reverse-proxy, firewall

##### README for additional insights
- The readme signals expansion beyond a simple Linux firewall/gateway into a fuller “Home-Ops” automation suite.

##### Elements
- Clear labels on each component (e.g., “Ansible Control Node,” “Proxmox VM: dhcp-server”)
- CI build & push
- VM provisioning
- Configuration / deployment flows
- Service request/response flows

## Diagram (Mermaid)

```mermaid
graph TB
    %% Control Plane
    subgraph "Control Plane"
        GH["GitHub Repo"]:::cp
        WF1["Workflow: kea-simple-build"]:::cp
        WF2["Workflow: kea-host-cmd-hook-build"]:::cp
        WF3["Workflow: powerdns-build"]:::cp
        CR["Container Registry"]:::cp
        TG["Terragrunt\n(root.hcl,\nproxmox/terragrunt.hcl,\ncommon.yaml,\nmodules)"]:::cp
        AN["Ansible Control Node"]:::cp
    end

    %% Data Plane
    subgraph "Data Plane"
        PM["Proxmox Cluster"]:::dp
        subgraph "VMs"
            VM1["VM: dhcp-server"]:::dp
            VM2["VM: dns-server"]:::dp
            VM3["VM: pi-hole"]:::dp
            VM4["VM: authentik"]:::dp
            VM5["VM: monitoring"]:::dp
            VM6["VM: firewall"]:::dp
        end
        subgraph "Containers"
            C1a["Kea DHCP Simple"]:::dp
            C1b["Kea DHCP Host-Cmd"]:::dp
            C2["PowerDNS"]:::dp
            C3["Pi-hole"]:::dp
            C4["Auth Service (SSO)"]:::dp
            C5["Prometheus"]:::dp
            C6["Grafana"]:::dp
            C7["Telegraf"]:::dp
            C8["NGINX Proxy"]:::dp
        end
        DB1["PostgreSQL"]:::db
    end

    Internet["Internet / LAN Devices"]:::external

    %% Connections - Control Plane
    GH --> WF1
    GH --> WF2
    GH --> WF3
    WF1 -->|"push image"| CR
    WF2 -->|"push image"| CR
    WF3 -->|"push image"| CR
    CR -->|"pull images"| AN
    TG -->|"Proxmox API"| PM
    AN -->|"SSH & playbooks"| VM1
    AN -->|"SSH & playbooks"| VM2
    AN -->|"SSH & playbooks"| VM3
    AN -->|"SSH & playbooks"| VM4
    AN -->|"SSH & playbooks"| VM5
    AN -->|"SSH & playbooks"| VM6

    %% Connections - Data Plane
    PM --> VM1
    PM --> VM2
    PM --> VM3
    PM --> VM4
    PM --> VM5
    PM --> VM6

    VM1 --> C1a
    VM1 --> C1b
    VM2 --> C2
    VM3 --> C3
    VM4 --> C4
    VM5 --> C5
    VM5 --> C6
    VM5 --> C7
    VM6 -->|"enforce rules"| VM* 

    C1a -->|"DHCP leases"| Internet
    C1b -->|"DHCP leases"| Internet
    C3 -->|"DNS queries"| Internet
    C2 -->|"authoritative DNS"| Internet
    C4 -->|"SSO auth"| Internet
    C7 -->|"metrics"| C5
    C7 -->|"metrics"| C6
    Internet --> C8
    C8 --> C4
    C8 --> C6
    C8 -->|"routes to PGAdmin, PDNS UI, Pi-hole"| C2
    C8 --> C3

    VM2 --> DB1
    VM4 --> DB1

    %% Click Events - Terragrunt
    click TG "https://github.com/nixknight/home-ops/blob/main/terragrunt/root.hcl"
    click TG "https://github.com/nixknight/home-ops/blob/main/terragrunt/proxmox/terragrunt.hcl"
    click TG "https://github.com/nixknight/home-ops/blob/main/terragrunt/common.yaml"
    click TG "https://github.com/nixknight/home-ops/tree/main/terragrunt/modules/"

    %% Click Events - Ansible
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/ansible.cfg"
    click AN "https://github.com/nixknight/home-ops/tree/main/ansible/inventory/"
    click AN "https://github.com/nixknight/home-ops/tree/main/ansible/extravars/"
    click AN "https://github.com/nixknight/home-ops/tree/main/ansible/roles/"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/common.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/kea.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/powerdns.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/pi-hole.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/monitoring.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/nginx.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/authentik.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/firewall.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/proxmox-vm-template.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/create-pgsql-db-users.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/data-services.yml"
    click AN "https://github.com/nixknight/home-ops/blob/main/ansible/playbooks/acme.yml"

    %% Click Events - Dockerfiles
    click C1a "https://github.com/nixknight/home-ops/tree/main/docker/kea/simple/Dockerfile"
    click C1b "https://github.com/nixknight/home-ops/tree/main/docker/kea/host-cmd-hook/Dockerfile"
    click C2 "https://github.com/nixknight/home-ops/tree/main/docker/powerdns/Dockerfile"

    %% Click Events - CI Workflows
    click WF1 "https://github.com/nixknight/home-ops/blob/main/.github/workflows/kea-simple-container-image-build.yml"
    click WF2 "https://github.com/nixknight/home-ops/blob/main/.github/workflows/kea-host-cmd-hook-container-image-build.yml"
    click WF3 "https://github.com/nixknight/home-ops/blob/main/.github/workflows/powerdns-container-image-build.yml"

    %% Click Events - Utilities
    click AN "https://github.com/nixknight/home-ops/tree/main/utils/ansible-vault-decryptor"

    %% Styles
    classDef cp fill:#D6EAF8,stroke:#3498DB,color:#154360
    classDef dp fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef db fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef external fill:#FADBD8,stroke:#E74C3C,color:#641E16
```
