infrapuzzle/AGENTS.md

AGENTS.md

Note

Infrapuzzle is the monorepo for my personal infrastructure, encompassing Kubernetes cluster provisioning, workload deployment, DNS management, and IoT monitoring.

Repository Structure & Documentation

This repository is divided into distinct domains, each with its own AGENTS.md or specialized documentation.

1. Bootstrap (bootstrap/)

• Purpose: Provisioning the single-node Kubernetes cluster (Haumdaucher).
• Tool: Kubespray (Ansible).
• Key File: init.sh (Source of Truth for versioning).
• Read: bootstrap/AGENTS.md

2. Kubernetes Workloads (k8s/)

• Purpose: Deploying applications and services to the cluster.
• Strict Namespace Rule: Every top-level subdirectory in k8s/ strictly corresponds to a Kubernetes namespace. Non-namespace folders, loose scripts, or documentation do not belong here.
• Constraints: Enforces ingress-nginx / traefik, cert-manager (Let's Encrypt), and git-crypt for secrets.
• OpenClaw: For OpenClaw AI agent deployment and troubleshooting, see k8s/openclaw/AGENTS.md and k8s/openclaw/TROUBLESHOOTING.md.
• Read: k8s/AGENTS.md

3. Terraform (terraform/)

• Purpose: Declarative core cloud infrastructure as code.
  • DNS Zones: haumdaucher.de, moritzgraf.de, ameliegraf.de, and others via OVH (ovh/ovh).
  • Cloud Services: Authentik SSO (authentik.tf), GCP APIs, Velero backup SA (gcp_backups.tf), OpenClaw calendar SA (gcp_calendar.tf), and Google Workspace MX/SPF/DKIM (google_workspace.tf).
  • Usage: cd terraform && terraform apply
• Read: terraform/AGENTS.md

4. Monitoring (monitoring/)

• Purpose: Physical ambient BLE sensor fleet monitoring across living areas.
• Tool: ESPHome.
• Devices: Temperature & humidity sensors, Xiaomi BLE plants, ESP32 bridges (muc-kitchen, muc-living, rgbg-living).
• Usage:

  cd monitoring
  esphome run config/<device>.secret.yml
  

• Read: monitoring/README.md

5. Knowledge Wiki & OpenClaw Tasks (knowledge-wiki/)

• Purpose: Shared personal knowledge wiki and task dispatch between OpenClaw (mobile/Telegram concierge) and Antigravity (local pair programming agent).
• Location: Git submodule knowledge-wiki/ at root of infrapuzzle (Git repo: https://git.moritzgraf.de/moritz/knowledge-wiki.git, branch main).
• Queue File: knowledge-wiki/tasks/antigravity.md.
• Workflow for Antigravity:
  • When the user asks to check tasks or pick up work from OpenClaw:
    1. Pull latest: git submodule update --remote knowledge-wiki (or git -C knowledge-wiki pull --rebase origin main)
    2. Read knowledge-wiki/tasks/antigravity.md to see pending items.
    3. Implement the chosen task in the appropriate repository files.
    4. Move the task to ## ✅ Completed Tasks with completion details and commit info.
    5. Push back: git -C knowledge-wiki commit -am "chore(tasks): complete <task>" && git -C knowledge-wiki push origin main.

6. Architecture Decision Records (docs/adr/)

• Purpose: Formal record of architectural decisions, technical trade-offs, and design standards across the monorepo.
• Format: MADR (Markdown Architectural Decision Records).
• Consulting ADRs: AI agents MUST consult docs/adr/ before designing or altering system architecture, agent topologies, or tool integration patterns.
• Key Records:
  • ADR 0001: Hybrid MCP Tool Search and Subagent Delegation for AI Agents
  • ADR 0002: OpenClaw Multi-Tier Model Selection, Latency Optimization, and Inference Economics
  • ADR 0003: Everything as Code (EaC) and Reproducible Declarative Infrastructure

7. Saschas Kronkorken Kreuzzug (projects/sasch40/)

• Purpose: Mobile-first 2.5D retro birthday adventure game for King Sascha's 40th jubilee (https://sasch40.haumdaucher.de).
• Key Rules: Prequel landing screen for QR codes, dynamic GameBoy arcade vs RPG layouts, real-photo character portraits, pure Web Audio synthesizer, competitive certificate scoring.
• Read: projects/sasch40/AGENTS.md

8. Moritz Graf Personal Website (projects/moritzgrafde/)

• Purpose: Personal homepage and portfolio for Moritz Graf (https://moritzgraf.de).
• Manifest: k8s/web/moritzgrafde.yaml (Namespace: web).
• Image: registry.haumdaucher.de/moritzgrafde:latest.
• Key Rules: Executive portfolio built with Vue 3, Vite, TypeScript, and Tailwind CSS served via Nginx in Docker.
• Read: projects/moritzgrafde/AGENTS.md

9. Haumdaucher Official Website (projects/haumdaucherde/)

• Purpose: Official community platform and club portal for Haumdaucher Regensburg (https://haumdaucher.de).
• Manifest: k8s/haumdaucher/haumdaucher.yaml (Namespace: haumdaucher).
• Image: registry.haumdaucher.de/haumdaucher-website:latest.
• Key Rules: PWA built with Vue 3, Vite, TypeScript, and Firebase Auth; dynamic theming with NAT mode easter egg; strict compliance with German Vereinsrecht (§ 5 DDG Impressum for n.e.V.); user creation and mail forwarding Apps Script automations.
• Read: projects/haumdaucherde/AGENTS.md

10. Grabengasse 7 Home Portal (projects/grabengasse/)

• Purpose: Local climate, weather, and environmental dashboard for Grabengasse 7 (https://grabengasse7.de).
• Manifests: k8s/grabengasse/ (frontend.yaml, backend.yaml, ingress.yaml in namespace grabengasse).
• Images: registry.haumdaucher.de/website/grabengasse_frontend:latest, registry.haumdaucher.de/website/grabengasse_backend:latest.
• Key Rules: Vue 3 retro pixel art frontend + FastAPI backend querying cluster Prometheus for Shelly WS90 weather telemetry.
• Read: projects/grabengasse/AGENTS.md

11. Kitchen e-Paper Display (projects/esphome_display_kitchen/)

• Purpose: Dedicated ESP32 microcontroller driving the Waveshare e-Paper status display in the kitchen.
• Integrations: Home Assistant Native API (input_text.epaper_message), Prometheus client, SNTP time sync.
• Key Tools: Interactive uv run flash.py wizard and ./send_message.sh CLI push messaging.
• Read: projects/esphome_display_kitchen/AGENTS.md

12. DuckDB Backend (projects/duckdb-backend/)

• Purpose: High-performance HTTP analytics and event tracking data service executing in-memory DuckDB queries against Knowledge Wiki JSONL datasets.
• Manifests: k8s/family/ (duckdb-backend.yaml, pvc.yaml, ingress.yaml in namespace family).
• Endpoints: Curated dashboards (/duckdb-api/v1/mila/dashboard, /duckdb-api/v1/moritz/dashboard), generic SQL queries (/duckdb-api/v1/query), and event tracking writes with Git sync.
• Read: projects/duckdb-backend/AGENTS.md

13. Mila Tracking Web App (projects/mila/)

• Purpose: Reactive mobile-first PWA for Mila's baby sleep, feeding, diaper tracking, and growth percentiles (https://family.haumdaucher.de/tracking/mila).
• Manifest: k8s/family/mila.yaml (Namespace: family).
• Key Rules: Vue 3, Vite, TypeScript, and Tailwind CSS; live wake timer; interactive 1-tap and custom-time tracking modal.
• Read: projects/mila/AGENTS.md

14. Moritz Health & Nutrition Web App (projects/moritz/)

• Purpose: Apple Health-inspired nutrition and metabolic balance dashboard (https://family.haumdaucher.de/tracking/moritz).
• Manifest: k8s/family/moritz.yaml (Namespace: family).
• Key Rules: Vue 3, Vite, TypeScript, and Tailwind CSS; net calorie balance hero, Garmin health breakdown, and quick meal logger.
• Read: projects/moritz/AGENTS.md

15. Shelly Taupunktlüfter (projects/shelly_taupunktluefter/)

• Purpose: Automated cellar ventilation controller ("Taupi") on Shelly Plug S Gen 3 to prevent mold growth using psychrometric calculations and BTHome BLE sensors.
• Usage: cd projects/shelly_taupunktluefter && terraform apply
• Key Rules: Sedlbauer LIM I decoupled mold danger evaluation, summer overheating and winter cold guards, optimal night drying window (03:00–07:00), and Prometheus metrics export.
• Read: projects/shelly_taupunktluefter/AGENTS.md

16. Utility Scripts (scripts/)

• Purpose: Cross-cutting operational and administration CLI scripts that do not belong inside Kubernetes namespace directories.
• Key Tools:
  • scripts/htpasswd.py: Generates bcrypt-hashed htpasswd credentials for ingress basic auth secrets.

17. Network & Router Integration (fritzbox/)

• Purpose: Site-to-Site WireGuard LAN coupling and DynDNS OVH synchronization for the home FritzBox router.
• Cluster Endpoint: k8s/wireguard/ (vpn.haumdaucher.de).
• Read: fritzbox/README.md

Global Constraints

• Secrets: git-crypt is used extensively. Ensure you have the unlock key before editing *.secret files.
• Identity:
  • Cluster: haumdaucher
  • Primary Domain: haumdaucher.de
  • User Identity: moritzgraf.de