Architecture Overview

High-Level Diagram

graph TD
    subgraph GitHub["GitHub (source of truth)"]
        repo["HomeKube repository\nmain branch"]
    end

    subgraph MacBook["MacBook (local)"]
        subgraph Minikube["Minikube Cluster"]
            subgraph flux["flux-system"]
                sc["source-controller\n(watches Git + Helm repos)"]
                kc["kustomize-controller\n(applies Kustomizations)"]
                hc["helm-controller\n(manages HelmReleases)"]
            end

            subgraph infra["Infrastructure"]
                cm["cert-manager\n(TLS automation)"]
                nginx["ingress-nginx\n(HTTP routing)"]
                cilium["Cilium\n(CNI + NetworkPolicy)"]
            end

            subgraph obs["Observability"]
                prom["Prometheus\n(metrics)"]
                grafana["Grafana\n(dashboards)"]
                hubble["Hubble UI\n(network flows)"]
            end
        end
    end

    repo -->|"pull (every 1h\nor on-demand)"| sc
    sc --> kc
    sc --> hc
    kc --> infra
    hc --> cm
    hc --> nginx
    hc --> prom
    hc --> grafana

---

Repository Structure

HomeKube/
├── clusters/
│   └── local/               # Flux Kustomization objects
│       ├── flux-system/     # Auto-created by flux bootstrap — do not edit
│       ├── kustomization.yaml
│       ├── infrastructure.yaml         # → infrastructure/controllers
│       ├── infrastructure-configs.yaml # → infrastructure/configs
│       ├── observability.yaml          # → observability/
│       └── network-policies.yaml       # → infrastructure/network-policies
│
├── infrastructure/
│   ├── controllers/         # HelmReleases: cert-manager, ingress-nginx
│   └── configs/             # Post-install: ClusterIssuer
│
├── observability/           # HelmRelease: kube-prometheus-stack
│
├── infrastructure/
│   └── network-policies/    # NetworkPolicy resources
│
├── apps/
│   ├── base/                # Base app manifests (Phase 3)
│   └── local/               # Local overlays (Phase 3)
│
└── docs/                    # This documentation site + ADRs

---

Dependency Chain

Flux Kustomizations are deployed in order via dependsOn:

graph LR
    FS["flux-system"] --> IC["infrastructure-controllers"]
    IC --> CFG["infrastructure-configs"]
    IC --> OBS["observability"]
    IC --> NP["network-policies"]

Kustomization	Deploys	Depends on
flux-system	Flux controllers	—
infrastructure-controllers	cert-manager, ingress-nginx	flux-system
infrastructure-configs	ClusterIssuer	infrastructure-controllers
observability	Prometheus, Grafana	infrastructure-controllers
network-policies	NetworkPolicies	infrastructure-controllers

---

Key Design Decisions

Decision	Choice	ADR
Local K8s runtime	Minikube + Docker driver	ADR-001
GitOps operator	FluxCD v2	ADR-002
Repo structure	Monorepo	ADR-003
Config management	Helm + Kustomize	ADR-004
Ingress	ingress-nginx	ADR-005
TLS	cert-manager	ADR-006
Observability	kube-prometheus-stack	ADR-007
CNI	Cilium	ADR-008