# spicyhek/homelab-infra architecture

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

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

## Overview

This repository is the desired-state and operational tooling for a small homelab: it runs web, NIDS, release-tracking, and status services on K3s, with Argo CD reconciliation and an AWS reliability plane. The main runtime path is Zeek traffic into NIDS, with scheduled backups and independent health probes; operators also use the host network guard and a scorecard for reliability and delivery. Some deployment relationships are documented in the README; unsampled manifests are represented by their exact enclosing directories, so their internal wiring is not asserted.

Main entry points: [`k8s/argocd`](https://github.com/spicyhek/homelab-infra/tree/main/k8s/argocd) (Argo CD), [`terraform/reliability-control-plane/lambda/probe/handler.py`](https://github.com/spicyhek/homelab-infra/blob/main/terraform/reliability-control-plane/lambda/probe/handler.py) (Reliability probes), [`k8s/apps/nids`](https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/nids) (NIDS service), [`scripts/reliability_scorecard.py`](https://github.com/spicyhek/homelab-infra/blob/main/scripts/reliability_scorecard.py) (Reliability scorecard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gitops["GitOps and Workloads"]
  node_repository["Git desired state<br/>[README.md]"]
  node_argocd["Argo CD"]
  node_site["Personal site"]
  node_status["Status API"]
  node_mybuilds["Release tracker"]
  node_cloudflared["Cloudflare Tunnel"]
end

subgraph group_network["Network Security"]
  node_zeek["Zeek sensor"]
  node_nids[("NIDS service")]
  node_nidsbackup["NIDS backup job"]
  node_networkguard["Host network guard<br/>[network_guard.py]"]
end

subgraph group_reliability["Reliability Plane"]
  node_probe["Reliability probes<br/>[handler.py]"]
  node_backupcheck["Backup validation<br/>[handler.py]"]
  node_aws[("AWS metrics and storage")]
  node_scorecard["Reliability scorecard"]
end

subgraph group_observability["Observability"]
  node_alloy["Metrics collectors"]
  node_grafanacloud[("Grafana Cloud")]
end

node_operator(("Operator"))

node_operator -->|"changes desired state"| node_repository
node_repository -->|"reconciles from"| node_argocd
node_argocd -->|"reconciles"| node_site
node_argocd -->|"reconciles"| node_status
node_argocd -->|"reconciles"| node_mybuilds
node_argocd -->|"reconciles"| node_nids
node_argocd -->|"reconciles"| node_zeek
node_argocd -->|"reconciles"| node_cloudflared
node_zeek -->|"forwards flow data"| node_nids
node_nidsbackup -->|"backs up database"| node_nids
node_probe -->|"checks health"| node_site
node_probe -->|"checks cluster status"| node_status
node_probe -->|"checks health"| node_nids
node_probe -->|"checks health"| node_mybuilds
node_probe -->|"publishes metrics"| node_aws
node_backupcheck -->|"validates backup and publishes metrics"| node_aws
node_scorecard -->|"collects availability"| node_aws
node_scorecard -->|"produces report"| node_operator
node_alloy -->|"sends metrics"| node_grafanacloud
node_operator -.->|"runs recovery tooling"| node_networkguard

click node_repository "https://github.com/spicyhek/homelab-infra/blob/main/README.md"
click node_argocd "https://github.com/spicyhek/homelab-infra/tree/main/k8s/argocd"
click node_site "https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/personal-site"
click node_status "https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/status-api"
click node_mybuilds "https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/mybuilds"
click node_zeek "https://github.com/spicyhek/homelab-infra/tree/main/k8s/daemonsets/zeek"
click node_nids "https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/nids"
click node_nidsbackup "https://github.com/spicyhek/homelab-infra/tree/main/k8s/backups"
click node_networkguard "https://github.com/spicyhek/homelab-infra/blob/main/host/control-plane/network_guard.py"
click node_probe "https://github.com/spicyhek/homelab-infra/blob/main/terraform/reliability-control-plane/lambda/probe/handler.py"
click node_backupcheck "https://github.com/spicyhek/homelab-infra/blob/main/terraform/reliability-control-plane/lambda/backup/handler.py"
click node_scorecard "https://github.com/spicyhek/homelab-infra/blob/main/scripts/reliability_scorecard.py"
click node_alloy "https://github.com/spicyhek/homelab-infra/tree/main/k8s/observability"
click node_cloudflared "https://github.com/spicyhek/homelab-infra/tree/main/k8s/edge/cloudflared"

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_repository,node_argocd,node_site,node_status,node_mybuilds,node_cloudflared toneBlue
class node_zeek,node_nids,node_nidsbackup,node_networkguard toneAmber
class node_probe,node_backupcheck,node_aws,node_scorecard toneMint
class node_alloy,node_grafanacloud toneRose
class node_operator toneIndigo
```

## Components

### GitOps and Workloads

- [Git desired state](https://github.com/spicyhek/homelab-infra/blob/main/README.md): `README.md`
- [Argo CD](https://github.com/spicyhek/homelab-infra/tree/main/k8s/argocd): `k8s/argocd`
- [Personal site](https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/personal-site): `k8s/apps/personal-site`
- [Status API](https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/status-api): `k8s/apps/status-api`
- [Release tracker](https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/mybuilds): `k8s/apps/mybuilds`
- [Cloudflare Tunnel](https://github.com/spicyhek/homelab-infra/tree/main/k8s/edge/cloudflared): `k8s/edge/cloudflared`

### Network Security

- [Zeek sensor](https://github.com/spicyhek/homelab-infra/tree/main/k8s/daemonsets/zeek): `k8s/daemonsets/zeek`
- [NIDS service](https://github.com/spicyhek/homelab-infra/tree/main/k8s/apps/nids): `k8s/apps/nids`
- [NIDS backup job](https://github.com/spicyhek/homelab-infra/tree/main/k8s/backups): `k8s/backups`
- [Host network guard](https://github.com/spicyhek/homelab-infra/blob/main/host/control-plane/network_guard.py): `host/control-plane/network_guard.py`

### Reliability Plane

- [Reliability probes](https://github.com/spicyhek/homelab-infra/blob/main/terraform/reliability-control-plane/lambda/probe/handler.py): `terraform/reliability-control-plane/lambda/probe/handler.py`
- [Backup validation](https://github.com/spicyhek/homelab-infra/blob/main/terraform/reliability-control-plane/lambda/backup/handler.py): `terraform/reliability-control-plane/lambda/backup/handler.py`
- **AWS metrics and storage**
- [Reliability scorecard](https://github.com/spicyhek/homelab-infra/blob/main/scripts/reliability_scorecard.py): `scripts/reliability_scorecard.py`

### Observability

- [Metrics collectors](https://github.com/spicyhek/homelab-infra/tree/main/k8s/observability): `k8s/observability`
- **Grafana Cloud**

### Other components

- **Operator**

## Connections

- Operator → Git desired state: changes desired state (evidence: `README.md`)
- Git desired state → Argo CD: reconciles from (evidence: `README.md`)
- Argo CD → Personal site: reconciles (evidence: `README.md`)
- Argo CD → Status API: reconciles (evidence: `README.md`)
- Argo CD → Release tracker: reconciles (evidence: `README.md`)
- Argo CD → NIDS service: reconciles (evidence: `README.md`)
- Argo CD → Zeek sensor: reconciles (evidence: `README.md`)
- Argo CD → Cloudflare Tunnel: reconciles (evidence: `README.md`)
- Zeek sensor → NIDS service: forwards flow data (evidence: `README.md`)
- NIDS backup job → NIDS service: backs up database (evidence: `README.md`)
- Reliability probes → Personal site: checks health (evidence: `terraform/reliability-control-plane/lambda/probe/handler.py`)
- Reliability probes → Status API: checks cluster status (evidence: `terraform/reliability-control-plane/lambda/probe/handler.py`)
- Reliability probes → NIDS service: checks health (evidence: `terraform/reliability-control-plane/lambda/probe/handler.py`)
- Reliability probes → Release tracker: checks health (evidence: `terraform/reliability-control-plane/lambda/probe/handler.py`)
- Reliability probes → AWS metrics and storage: publishes metrics (evidence: `terraform/reliability-control-plane/lambda/probe/handler.py`)
- Backup validation → AWS metrics and storage: validates backup and publishes metrics (evidence: `terraform/reliability-control-plane/lambda/backup/handler.py`)
- Reliability scorecard → AWS metrics and storage: collects availability (evidence: `scripts/reliability_scorecard.py`)
- Reliability scorecard → Operator: produces report (evidence: `scripts/reliability_scorecard.py`)
- Metrics collectors → Grafana Cloud: sends metrics (evidence: `README.md`)
- Operator → Host network guard: runs recovery tooling
