docs: complete overhaul of root README.md with architecture diagram and comprehensive guide

README.md

@@ -1,7 +1,84 @@
-# RKE2 Single-Node-Cluster for Homelab
+# ⚓ RKE2 Single-Node Cluster | Homelab
 
-This is how I set up my RKE2 single node cluster for my homelab.
+Dieses Repository enthält die vollständige Infrastruktur-Konfiguration (Infrastructure as Code) für meinen RKE2-basierten Kubernetes Single-Node-Cluster auf einem **ASUS PN51**.
 
-## External dependencies
+## 🚀 Übersicht
-- Authentik instance for SSO
+Das Ziel dieses Projekts ist ein hochautomatisierter Cluster, der dem **"Set and Forget"**-Prinzip folgt. Von der IP-Ankündigung via BGP bis zur automatischen Zertifikatsausstellung ist alles in GitOps-Workflows abgebildet.
-- Phase Secrets Manager to keep all secrets in a safe space
+
+### 📊 System-Architektur
+```mermaidjs
+graph TD
+    subgraph "External World / Home Network"
+        Router[UniFi Dream Machine]
+        Auth[Authentik SSO]
+        Vault[Phase Secrets]
+    end
+
+    subgraph "ASUS PN51 Node (openSUSE Leap)"
+        RKE2[⚓ RKE2 Engine]
+        Cilium[🛡️ Cilium eBPF & BGP]
+        EG[🚀 Envoy Gateway API]
+        Argo[🎡 ArgoCD GitOps]
+    end
+
+    Router <-->|BGP Peering| Cilium
+    Cilium --> EG
+    EG -->|Traffic Control| Apps[Immich, n8n, etc.]
+    Argo -->|Sync| RKE2
+    Vault -->|Inject Secrets| Argo
+    Auth -->|OIDC| Argo
+```
+
+---
+
+## 🛠️ Tech-Stack
+| Schicht | Komponente | Beschreibung |
+| :--- | :--- | :--- |
+| **OS** | openSUSE Leap 16.0 | Stabiles Fundament für den ASUS PN51 |
+| **K8S** | RKE2 (v1.34.4) | Sicherheitsorientierte Kubernetes-Distribution |
+| **Network** | Cilium (eBPF) | High-Performance Networking & BGP |
+| **Gateway** | Envoy Gateway | Moderne Gateway API statt klassischem Ingress |
+| **GitOps** | Argo CD | Vollautomatische Applikations-Bereitstellung |
+| **Secrets** | Phase | Sichere Injektion von Umgebungsvariablen |
+| **DNS** | External-DNS | Sync von Hostnames mit UniFi & Cloudflare |
+| **Certs** | Cert-Manager | TLS via Let's Encrypt (DNS-01 Challenge) |
+
+---
+
+## 📂 Repository Struktur
+Die Konfiguration ist chronologisch nach der Installationsreihenfolge aufgebaut:
+
+- `01_unifi_gateway_setup/`: Vorbereitung des Routers (BGP Config).
+- `02_rke2_installation/`: Grundinstallation von Kubernetes auf dem Node.
+- `03_netzwerk_und_gateway/`: Deployment von Cilium & Envoy Gateway Controller.
+- `04_envoy_gateway_preparation/`: BGP IP-Pools und initiale Shared Gateways.
+- `05_base_apps_and_tools/`: Hilfsmittel wie Cert-Manager, External-DNS & Phase.
+- `06_argocd_installation/`: Installation von Argo CD inkl. SSO-Anbindung.
+- `07_bootstrap_argocd/`: Der "App-of-Apps" Bootstrap für die Automatisierung.
+- `08_cluster_infrastructure/`: Core-Services (NFS Storage, VPA, etc.).
+- `09_homelab_apps/`: Benutzer-Applikationen (Immich, Ghostfolio, n8n, etc.).
+
+---
+
+## 🏗️ Getting Started
+Um den Cluster neu aufzusetzen, folgen Sie den detaillierten `installation_instructions.md` in den jeweiligen Ordnern `01` bis `07`.
+
+Ab Schritt `07` übernimmt ArgoCD das Management:
+1.  **ApplicationSets** scannen die Ordner `08` und `09`.
+2.  Jede neue Applikation erhält automatisch:
+    - Eine LoadBalancer VIP (via BGP).
+    - Einen DNS-Eintrag (via External-DNS).
+    - Ein TLS-Zertifikat (via Cert-Manager).
+    - SSO-Schutz (via Authentik/OIDC).
+
+---
+
+## 🔑 Externe Abhängigkeiten
+Für den vollen Funktionsumfang werden folgende Dienste benötigt:
+- **UniFi Router:** Für BGP Peering und lokales DNS.
+- **Authentik:** Zentraler Identity Provider (SSO).
+- **Phase.dev:** Cloud-Konsole für das Secret-Management.
+- **Cloudflare:** DNS-Provider für die ACME DNS-01 Challenge.
+
+---
+*Dokumentation & Konfiguration gepflegt durch Gemini CLI | Stand: 06. März 2026*