cluster/docs/repositories.md

Repository Details & Modules

Dit document bevat specifieke details over de repositories in deze workspace, inclusief mappenstructuur, protocollen en configuraties.

---

1. 🍺 HERMS Repository

• Pad: /home/bart/git/cluster/HERMS
• Git Remote: https://git.bnhmeijer.nl/bart/HERMS.git
• Doel: Geautomatiseerd Heat Exchange Recirculating Mash System (bierbrouwen).

Submodules & Componenten

• frontend/:
  • Next.js, React, Tailwind CSS.
  • Geïmplementeerd met het SevenGrid Aurora Dark Mode thema (#0A0F12, Aurora Teal #1DC7B7, Coral #E26F3A).
  • Realtime updates via WebSockets (/api/ws) en NATS opslag events (herms.storage.>).
  • Live monitoring voor vaten: HLT (Warmtewisselaar), MLT (Maischketel), BK (Kookketel).
• herms-controller/:
  • Rust microservice.
  • Beheert timers, receptstappen en automatische PID/doeltemperatuurberekeningen op basis van ketelafhankelijkheden (depends_on, difference_abs, delay_minutes).
  • Publiceert doeltemperaturen naar MQTT.
• herms-storage/:
  • Rust REST API service met NATS integratie.
  • Slaat recepten, batchlogs en telemetrie op.
  • Schrijft metingen door naar InfluxDB (Line Protocol).
• gravitymon-2-nats/:
  • Rust microservice die HTTP POST data van Gravitymon hydrometers ontvangt en op NATS publiceert.
• firmware/ & mock-esp/:
  • firmware/: C++ PlatformIO code voor de ESP32 microcontroller op de installatie.
  • mock-esp/: Python simulator voor het nabootsen van keteltemperaturen, pompen en verwarmingselementen over MQTT.
• bierpcb/:
  • KiCad PCB project met schema's, relais-aansturingen, thermokoppelingangscircuits (MAX31855/MAX31856) en I2C IO expanders.
• recepten/:
  • JSON bierrecepten met stappen (maischstappen, kooktijden, ingrediënten).

MQTT Protocol Regels

• Base topic: <prefix>/<installation_id>/ (bijv. avr59/hermsdev/ of avr59/installation1/).
• KeteI Identifiers (<idx>): Altijd string, nooit indexnummer (hlt, mlt, boil).
• Command-to-State regel: Een commando op .../<endpoint>/cmd MOET direct door de ontvanger worden bevestigd op .../<endpoint>/state met retain: true.
• Telemetry: Actuele temperatuur op <base>heater/<idx>/temperature/state (payload bijv. "65.2").

---

2. 🌐 cluster-infra Repository

• Pad: /home/bart/git/cluster/cluster-infra
• Git Remote: https://git.bnhmeijer.nl/bart/cluster-infra.git
• Doel: Gedeelde infrastructurele componenten en middleware.

Aanwezige Services

• postgresql/: PostgreSQL cluster configuratie en persistent storage.
• mongodb/: MongoDB replica/single instance.
• influxdb/: InfluxDB time-series database.
• rabbitmq/: AMQP message broker.
• mosquitto/: Eclipse Mosquitto MQTT broker.
• dnsmasq/: Lokale DNS caching, DHCP en NTP-optie uitgifte.
• ntp/: Lokale Chrony NTP tijdserver (UDP 123) voor LAN en IoT apparaten.
• email-service/: Interne mailrelay / notificatiedienst.
• label-service/: gLabels template rendering naar PDF, ZPL II en PNG via JSON API.
• infra-web/: Dashboard/webinterface voor infrastructuurbeheer.
• vhosts/: Apache/Nginx SSL en non-SSL reverse proxy configuraties voor bnhmeijer.nl domeinen.
• argocd/: ApplicationSet configuratie voor automatische ontdekking van workloads.

Hoe een nieuwe service toevoegen aan cluster-infra

1. Maak een map aan: mkdir -p <service-name>/k8s
2. Plaats eventueel een Dockerfile in <service-name>/.
3. Voeg Kubernetes manifests toe in <service-name>/k8s/ (deployment.yaml, service.yaml, kustomization.yaml).
4. Commit & push naar main. De Gitea Actions workflow bouwt en synchroniseert dit automatisch naar k8s-infra-vmserver.

---

3. 🚀 k8s-infra-vmserver Repository

• Pad: /home/bart/git/cluster/k8s-infra-vmserver
• Git Remote: https://git.bnhmeijer.nl/bart/k8s-infra-vmserver.git
• Doel: GitOps source-of-truth voor ArgoCD.

Mappenstructuur

• workloads/:
  • cluster-infra/: Wordt automatisch gevuld door CI/CD wanneer componenten in cluster-infra wijzigen.
  • demo/: Bevat de demonstratieapplicatie (podinfo) en bijbehorende Gateway API HTTPRoute (/demo).
  • herms/: De productiemanifests voor de HERMS microservices.

---

4. 🏠 smart-home Repository

• Pad: /home/bart/git/cluster/smart-home
• Git Remote: https://git.bnhmeijer.nl/bart/smart-home.git
• Doel: Smart home configuraties (Home Assistant integraties, scripts, automatiseringen).
• Status: In initiële opstartfase.

---

5. 🎬 htpc Repository

• Pad: /home/bart/git/cluster/htpc
• Git Remote: https://git.bnhmeijer.nl/bart/htpc.git
• Doel: HTPC & Media platform configuraties, deployments en automatisering.

Beheerde Services & Stacks

• Jellyfin: Media streamer en afspeelinterface voor audio/video.
• *Arr Suite: Sonarr, Radarr, Lidarr, Bazarr voor geautomatiseerd content- en ondertitelbeheer.
• Indexer & Downloaders: Prowlarr/Jackett, SABnzbd, torrent clients.

GitOps Workflow

• Manifests bevinden zich in k8s/ en worden via Gitea Actions gesynchroniseerd naar k8s-infra-vmserver onder workloads/htpc/.

---

6. 🏢 eendoeserver Repository

• Pad: /home/bart/git/cluster/eendoeserver
• Git Remote: https://git.bnhmeijer.nl/bart/eendoeserver.git
• Doel: Website eendoe.nl en Apache VirtualHost configuraties van web03.

---

7. 📦 package-repo Repository

• Pad: /home/bart/git/cluster/package-repo
• Git Remote: https://git.bnhmeijer.nl/bart/package-repo.git
• Doel: Debian/APT package repository bronnen, build-scripts en distributie.

---

8. 📺 jellyfin-client Repository

• Pad: /home/bart/git/cluster/jellyfin-client
• Git Remote: https://git.bnhmeijer.nl/bart/jellyfin-client.git
• Doel: HTPC client applicatie & YouTube video receiver voor Linux mini-PC's.
• Componenten:
  • Python WebSocket client sessie gekoppeld aan de centrale Jellyfin server.
  • MPV video player controller met hardwareversnelling via IPC unix socket.
  • Geëmuleerde Kodi JSON-RPC server (:8080, :9090) voor bediening via Yatse.
  • Web remote / REST API (:8097) voor mobiel YouTube links delen (yt-dlp).
  • jellyfin-kiosk-rs: Rust-gebaseerde kiosk launcher.

---

9. 📻 jellyfinradio Repository

• Pad: /home/bart/git/cluster/jellyfinradio
• Git Remote: https://github.com/brupje/jellyfinradio.git
• Doel: Radio stream scheduler, Icecast streamer en audio/video rendering gekoppeld aan Jellyfin.
• Componenten:
  • Python webserver en scheduler voor radio streams.
  • Icecast watcher & audio/video writers via FFmpeg.
  • Jellyfin API client integratie voor playlists en media selectie.