# Platform Overzicht & Architectuur

Dit document biedt een integraal overzicht van het homelab- en serverplatform gehost op `vmserver` (`10.2.0.4`) binnen het domein `bnhmeijer.nl`.

---

## 🎯 Doel & Filosofie van het Platform

Het platform fungeert als een betrouwbare, geautomatiseerde en zelf-gehoste infrastructurele backbone voor:
1. **Centrale infrastructuurdiensten**: Databases, message brokers en interne netwerkdiensten.
2. **GitOps & CI/CD**: Volledig geautomatiseerde build- en deploymentpijplijnen vanaf broncode tot Kubernetes pod.
3. **Smart Home & IoT**: Integratie van domotica (Home Assistant) en sensoren in het thuisnetwerk.
4. **Gespecialiseerde Automatisering (HERMS)**: Een geavanceerd biersysteem met sensoren, actuatoren, microservices en webinterfaces.

---

## 🏛️ Systeemlagen

Het platform is opgebouwd in duidelijke scheiding van lagen:

```mermaid
flowchart TD
    Internet([Publiek Internet / Lokaal LAN]) --> ApacheEdge["Apache Reverse Proxy (vmserver: 10.2.0.4)"]
    
    subgraph HostLevel ["Host Laag (vmserver / bare-metal)"]
        ApacheEdge
        Gitea["Gitea (git.bnhmeijer.nl)"]
        Keycloak["Keycloak (login.bnhmeijer.nl)"]
        MediaDiensten["Media & Storage (Jellyfin, Nextcloud, *Arr)"]
        DnsmasqHost["Dnsmasq (Lokale DNS / DHCP)"]
    end

    ApacheEdge -->|SSL / OIDC Terminatie| Keycloak
    ApacheEdge -->|Reverse Proxy| Gitea
    ApacheEdge -->|Reverse Proxy| MediaDiensten
    ApacheEdge -->|"Cluster Ingress (NodePort 32608)"| EnvoyGateway["Envoy Gateway API (k8s)"]

    subgraph K8sCluster ["Kubernetes Cluster"]
        EnvoyGateway --> HTTPRoutes[HTTPRoutes]
        
        subgraph Namespaces
            subgraph NS_ClusterInfra ["namespace: cluster-infra"]
                Postgres[(PostgreSQL)]
                Mongo[(MongoDB)]
                Influx[(InfluxDB)]
                RabbitMQ[(RabbitMQ)]
                Mosquitto[Mosquitto MQTT]
                InfraWeb[Infra Web Dashboard]
            end
            
            subgraph NS_SmartHome ["namespace: smart-home"]
                HomeAssistant[Home Assistant]
            end
            
            subgraph NS_HERMS ["namespace: herms"]
                HermsFrontend[HERMS Web UI]
                HermsController[HERMS Controller]
                HermsStorage[HERMS Storage]
                NATS[NATS Broker]
            end

            subgraph NS_ArgoCD ["namespace: argocd"]
                ArgoCD[ArgoCD ApplicationSets]
            end
        end
        
        HTTPRoutes --> InfraWeb
        HTTPRoutes --> HomeAssistant
        HTTPRoutes --> HermsFrontend
    end

    subgraph GitOpsPipeline ["CI/CD & GitOps"]
        Gitea -->|Gitea Actions CI| ContainerReg[Gitea Container Registry]
        ContainerReg --> GitOpsCommit[Update manifests in k8s-infra-vmserver]
        GitOpsCommit --> ArgoCD
        ArgoCD -->|Reconcile & Deploy| Namespaces
    end
```

---

## 📦 Repositories & Submodules

De werkmap `/home/bart/git/cluster` is gestructureerd als een **Git superproject** dat de verschillende subsystemen als submodules integreert:

| Submodule | Doel | Primaire Stack |
| :--- | :--- | :--- |
| **[`cluster-infra`](file:///home/bart/git/cluster/cluster-infra)** | Kerninfrastructuur & databases in K8s | PostgreSQL, MongoDB, InfluxDB, RabbitMQ, Mosquitto, Dnsmasq, Apache vhosts |
| **[`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver)** | GitOps repository gemonitord door ArgoCD | Kubernetes Kustomize manifests, HTTPRoutes, Service definities |
| **[`HERMS`](file:///home/bart/git/cluster/HERMS)** | Geautomatiseerd brouwplatform (brouwautomatisering) | Rust microservices, Next.js / TypeScript GUI, ESP32 C++, KiCad PCB |
| **[`smart-home`](file:///home/bart/git/cluster/smart-home)** | Huisautomatisering & IoT | Home Assistant, netwerk- en migratiescripts |
| **[`htpc`](file:///home/bart/git/cluster/htpc)** | HTPC & Media Services Platform | Jellyfin, *Arr stack, K8s manifests, GitOps |
| **[`eendoeserver`](file:///home/bart/git/cluster/eendoeserver)** | Web & Reverse Proxy web03 | Apache vhosts, HTML, SASS |
| **[`package-repo`](file:///home/bart/git/cluster/package-repo)** | Debian Package Repository | Debian packaging, Gitea Actions |
| **[`jellyfin-client`](file:///home/bart/git/cluster/jellyfin-client)** | HTPC Client & YouTube Receiver | Python, Rust, MPV IPC, Kodi JSON-RPC |
| **[`jellyfinradio`](file:///home/bart/git/cluster/jellyfinradio)** | Jellyfin Radio & Live Streamer | Python, FFMPEG, Icecast |

---

## 🔒 Beveiliging, Ingress & Identiteitsbeheer

1. **SSL / TLS**:
   * Alle inkomende HTTPS-verbindingen worden afgehandeld door Apache met geautomatiseerde Let's Encrypt SSL-certificaten.
2. **Authenticatie & Autorisatie (OIDC)**:
   * Beschermde diensten worden beveiligd via `mod_auth_openidc` gekoppeld aan de centrale Keycloak-instantie (`https://login.bnhmeijer.nl`).
3. **Cluster Routing**:
   * Apache fungeert als edge gateway en forwardt verkeer bestemd voor Kubernetes pods naar **Envoy Gateway** via NodePort `127.0.0.1:32608`. Envoy routeert vervolgens op basis van `HTTPRoute` resources in de K8s namespaces.

---

## 🔄 GitOps Workflow

De broncode en configuraties worden beheerd volgens strikte GitOps-principes:
1. **Wijziging in Broncode**: Een ontwikkelaar pusht code naar `main` in bijv. `cluster-infra` of `HERMS`.
2. **CI Pipeline (Gitea Actions)**:
   * Detecteert gewijzigde componenten via `dorny/paths-filter`.
   * Bouwt geoptimaliseerde Docker images en pusht deze naar de private Gitea container registry.
   * Werkt de container image tag bij in de GitOps-repository [`k8s-infra-vmserver`](file:///home/bart/git/cluster/k8s-infra-vmserver).
3. **CD Reconciliatie (ArgoCD)**:
   * ArgoCD detecteert de gewijzigde manifests in `k8s-infra-vmserver`.
   * Past automatisch een rolling update / sync toe op de Kubernetes cluster workloads.

---

## 📚 Verder Lezen

* **[Systeemarchitectuur & GitOps Details](file:///home/bart/git/cluster/docs/architecture.md)**
* **[Live Cluster Status & Hardware](file:///home/bart/git/cluster/docs/cluster-status.md)**
* **[Apache Reverse Proxy & VHosts](file:///home/bart/git/cluster/docs/apache-reverse-proxy.md)**
* **[Repository- & Module-overzicht](file:///home/bart/git/cluster/docs/repositories.md)**
* **[AI Agent & Developer Cheatsheet](file:///home/bart/git/cluster/docs/agent-cheatsheet.md)**