# osnabrugge/home-ops architecture

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

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

## Overview

This repository is a GitOps-managed home-infrastructure estate: operators maintain Talos and Kubernetes configuration, bootstrap the cluster’s critical dependencies, and Flux reconciles the remaining applications from the repository. The main result is a running homelab with networking, storage, access, backup, and monitoring capabilities. The graph groups runtime infrastructure by responsibility and includes the documented AI-triage pilot. Relationships are limited to README-described flows; application internals and most wiring were not sampled, so those connections are omitted.

Main entry points: [`bootstrap/helmfile/apps.yaml`](https://github.com/osnabrugge/home-ops/blob/main/bootstrap/helmfile/apps.yaml) (Bootstrap Chain), [`kubernetes/apps/flux-system`](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/flux-system) (Flux Reconciliation), [`kubernetes/apps/ai/litellm`](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/ai/litellm) (AI Model Routing), [`kubernetes/apps/kopiur-system/kopiur`](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/kopiur-system/kopiur) (PVC Backups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Cluster Bootstrap"]
  node_bootstrap_chain["Bootstrap Chain<br/>[apps.yaml]"]
  node_talos["Talos Nodes"]
  node_flux["Flux Reconciliation"]
end

subgraph group_platform["Cluster Platform"]
  node_network["Cluster Networking"]
  node_dns["Cluster DNS"]
  node_certs["Certificates"]
  node_secrets["Secret Management"]
  node_storage["Cluster Storage"]
  node_local_storage["Local Storage"]
  node_external_access["External Access"]
end

subgraph group_operations["Operations"]
  node_backups["PVC Backups"]
  node_garage[("Garage S3")]
  node_observability["Monitoring Stack"]
  node_alert_triage["Alert Triage<br/>[triage.py]"]
end

subgraph group_workloads["User Workloads"]
  node_workloads["Home Applications"]
  node_identity["Identity Services"]
end

subgraph group_ai["AI Workflows"]
  node_ai_router["AI Model Routing"]
  node_local_models["Local Models"]
  node_readonly_triage["Read-only Triage<br/>[triage_readonly.py]"]
  node_triage_worker["Scheduled Triage<br/>[worker.py]"]
  node_kritika["Kritika Pilot<br/>[policy.py]"]
end

node_operator(("Home Operator"))
node_repo["Infrastructure Repo"]
node_github(("GitHub"))
node_azure_kv[("Azure Key Vault")]
node_kopia_s3[("Kopia / Garage S3")]

node_operator -->|"maintains"| node_repo
node_repo -->|"configures"| node_talos
node_repo -->|"defines"| node_bootstrap_chain
node_bootstrap_chain -->|"installs first"| node_network
node_bootstrap_chain -->|"installs next"| node_dns
node_bootstrap_chain -->|"installs after"| node_certs
node_bootstrap_chain -->|"installs after"| node_secrets
node_bootstrap_chain -->|"installs after"| node_flux
node_repo -->|"reconciled by"| node_flux
node_flux -->|"reconciles"| node_workloads
node_flux -->|"reconciles"| node_storage
node_flux -->|"reconciles"| node_observability
node_flux -->|"reconciles"| node_backups
node_backups -->|"backs up to"| node_kopia_s3
node_observability -.->|"alerts feed"| node_alert_triage
node_azure_kv -->|"supplies secrets"| node_secrets
node_external_access -.->|"exposes services"| node_workloads
node_readonly_triage -->|"uses model routing"| node_ai_router
node_triage_worker -.->|"uses model routing"| node_ai_router
node_ai_router -.->|"routes to"| node_local_models
node_github -.->|"review pilot"| node_kritika

click node_bootstrap_chain "https://github.com/osnabrugge/home-ops/blob/main/bootstrap/helmfile/apps.yaml"
click node_talos "https://github.com/osnabrugge/home-ops/tree/main/talos/nodes"
click node_flux "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/flux-system"
click node_network "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/network"
click node_dns "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/kube-system"
click node_certs "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/cert-manager"
click node_secrets "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/external-secrets"
click node_storage "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/rook-ceph"
click node_local_storage "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/openebs-system"
click node_backups "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/kopiur-system/kopiur"
click node_observability "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/observability/kube-prometheus-stack"
click node_alert_triage "https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/observability/alert-triage/app/triage.py"
click node_external_access "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/network/cloudflare-tunnel"
click node_workloads "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/default"
click node_identity "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/auth"
click node_ai_router "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/ai/litellm"
click node_local_models "https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/ai/ollama"
click node_readonly_triage "https://github.com/osnabrugge/home-ops/blob/main/scripts/triage_readonly.py"
click node_triage_worker "https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/ai/triage-worker/app/worker.py"
click node_kritika "https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/kritika-system/kritika/app/policy.py"

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_bootstrap_chain,node_talos,node_flux toneBlue
class node_network,node_dns,node_certs,node_secrets,node_storage,node_local_storage,node_external_access,node_azure_kv,node_kopia_s3 toneAmber
class node_backups,node_garage,node_observability,node_alert_triage toneMint
class node_workloads,node_identity toneRose
class node_ai_router,node_local_models,node_readonly_triage,node_triage_worker,node_kritika,node_operator,node_repo,node_github toneIndigo
```

## Components

### Cluster Bootstrap

- [Bootstrap Chain](https://github.com/osnabrugge/home-ops/blob/main/bootstrap/helmfile/apps.yaml): `bootstrap/helmfile/apps.yaml`
- [Talos Nodes](https://github.com/osnabrugge/home-ops/tree/main/talos/nodes): `talos/nodes`
- [Flux Reconciliation](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/flux-system): `kubernetes/apps/flux-system`

### Cluster Platform

- [Cluster Networking](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/network): `kubernetes/apps/network`
- [Cluster DNS](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/kube-system): `kubernetes/apps/kube-system`
- [Certificates](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/cert-manager): `kubernetes/apps/cert-manager`
- [Secret Management](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/external-secrets): `kubernetes/apps/external-secrets`
- [Cluster Storage](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/rook-ceph): `kubernetes/apps/rook-ceph`
- [Local Storage](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/openebs-system): `kubernetes/apps/openebs-system`
- [External Access](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/network/cloudflare-tunnel): `kubernetes/apps/network/cloudflare-tunnel`

### Operations

- [PVC Backups](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/kopiur-system/kopiur): `kubernetes/apps/kopiur-system/kopiur`
- **Garage S3**
- [Monitoring Stack](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/observability/kube-prometheus-stack): `kubernetes/apps/observability/kube-prometheus-stack`
- [Alert Triage](https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/observability/alert-triage/app/triage.py): `kubernetes/apps/observability/alert-triage/app/triage.py`

### User Workloads

- [Home Applications](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/default): `kubernetes/apps/default`
- [Identity Services](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/auth): `kubernetes/apps/auth`

### AI Workflows

- [AI Model Routing](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/ai/litellm): `kubernetes/apps/ai/litellm`
- [Local Models](https://github.com/osnabrugge/home-ops/tree/main/kubernetes/apps/ai/ollama): `kubernetes/apps/ai/ollama`
- [Read-only Triage](https://github.com/osnabrugge/home-ops/blob/main/scripts/triage_readonly.py): `scripts/triage_readonly.py`
- [Scheduled Triage](https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/ai/triage-worker/app/worker.py): `kubernetes/apps/ai/triage-worker/app/worker.py`
- [Kritika Pilot](https://github.com/osnabrugge/home-ops/blob/main/kubernetes/apps/kritika-system/kritika/app/policy.py): `kubernetes/apps/kritika-system/kritika/app/policy.py`

### Other components

- **Home Operator**
- **Infrastructure Repo**
- **GitHub**
- **Azure Key Vault**
- **Kopia / Garage S3**

## Connections

- Home Operator → Infrastructure Repo: maintains (evidence: `README.md`)
- Infrastructure Repo → Talos Nodes: configures (evidence: `README.md`)
- Infrastructure Repo → Bootstrap Chain: defines (evidence: `README.md`)
- Bootstrap Chain → Cluster Networking: installs first (evidence: `README.md`)
- Bootstrap Chain → Cluster DNS: installs next (evidence: `README.md`)
- Bootstrap Chain → Certificates: installs after (evidence: `README.md`)
- Bootstrap Chain → Secret Management: installs after (evidence: `README.md`)
- Bootstrap Chain → Flux Reconciliation: installs after (evidence: `README.md`)
- Infrastructure Repo → Flux Reconciliation: reconciled by (evidence: `README.md`)
- Flux Reconciliation → Home Applications: reconciles (evidence: `README.md`)
- Flux Reconciliation → Cluster Storage: reconciles (evidence: `README.md`)
- Flux Reconciliation → Monitoring Stack: reconciles (evidence: `README.md`)
- Flux Reconciliation → PVC Backups: reconciles (evidence: `README.md`)
- PVC Backups → Kopia / Garage S3: backs up to (evidence: `README.md`)
- Monitoring Stack → Alert Triage: alerts feed
- Azure Key Vault → Secret Management: supplies secrets (evidence: `README.md`)
- External Access → Home Applications: exposes services
- Read-only Triage → AI Model Routing: uses model routing (evidence: `README.md`)
- Scheduled Triage → AI Model Routing: uses model routing
- AI Model Routing → Local Models: routes to
- GitHub → Kritika Pilot: review pilot