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: Infrastructure as Code divided into two symmetrical modules:
  • Cloud & DNS (terraform/infrastructure/):
    • DNS Zones: haumdaucher.de, moritzgraf.de, ameliegraf.de, and others via OVH (ovh/ovh).
    • Cloud Services: Authentik SSO (authentik.tf), GCP APIs, backups, and Google Workspace MX/SPF/DKIM.
    • Usage: cd terraform/infrastructure && terraform apply
  • Smart Home Shelly Automation (terraform/shelly/):
    • Taupi Cellar Mold Ventilation: Automates Shelly Plug S with psychrometric dew point calculations (Taupi-4.0.js) and BTHome Bluetooth sensor telemetry.
    • Usage: cd terraform/shelly && terraform apply
• Read: terraform/shelly/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. 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.

13. 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