133 lines
10 KiB
Markdown
133 lines
10 KiB
Markdown
# 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/AGENTS.md) (`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](./bootstrap/AGENTS.md)
|
||
|
||
### 2. [Kubernetes Workloads](./k8s/AGENTS.md) (`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](./k8s/openclaw/AGENTS.md) and [k8s/openclaw/TROUBLESHOOTING.md](./k8s/openclaw/TROUBLESHOOTING.md).
|
||
* **Read**: [k8s/AGENTS.md](./k8s/AGENTS.md)
|
||
|
||
### 3. [Terraform](./terraform/AGENTS.md) (`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](./terraform/AGENTS.md)
|
||
|
||
### 4. Monitoring (`monitoring/`)
|
||
* **Purpose**: Physical ambient BLE sensor fleet monitoring across living areas.
|
||
* **Tool**: [ESPHome](https://esphome.io).
|
||
* **Devices**: Temperature & humidity sensors, Xiaomi BLE plants, ESP32 bridges (`muc-kitchen`, `muc-living`, `rgbg-living`).
|
||
* **Usage**:
|
||
```bash
|
||
cd monitoring
|
||
esphome run config/<device>.secret.yml
|
||
```
|
||
* **Read**: [monitoring/README.md](./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](https://adr.github.io/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](docs/adr/0001-hybrid-mcp-tool-search-and-subagents.md)
|
||
* [ADR 0002: OpenClaw Multi-Tier Model Selection, Latency Optimization, and Inference Economics](docs/adr/0002-openclaw-model-selection-tiering-and-economics.md)
|
||
* [ADR 0003: Everything as Code (EaC) and Reproducible Declarative Infrastructure](docs/adr/0003-everything-as-code-and-reproducible-infrastructure.md)
|
||
|
||
### 7. [Saschas Kronkorken Kreuzzug](./projects/sasch40/AGENTS.md) (`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](./projects/sasch40/AGENTS.md)
|
||
|
||
### 8. [Moritz Graf Personal Website](./projects/moritzgrafde/AGENTS.md) (`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](./projects/moritzgrafde/AGENTS.md)
|
||
|
||
### 9. [Haumdaucher Official Website](./projects/haumdaucherde/AGENTS.md) (`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](./projects/haumdaucherde/AGENTS.md)
|
||
|
||
### 10. [Grabengasse 7 Home Portal](./projects/grabengasse/AGENTS.md) (`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](./projects/grabengasse/AGENTS.md)
|
||
|
||
### 11. [Kitchen e-Paper Display](./projects/esphome_display_kitchen/AGENTS.md) (`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](./projects/esphome_display_kitchen/AGENTS.md)
|
||
|
||
### 12. [DuckDB Backend](./projects/duckdb-backend/AGENTS.md) (`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](./projects/duckdb-backend/AGENTS.md)
|
||
|
||
### 13. [Mila Tracking Web App](./projects/mila/AGENTS.md) (`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](./projects/mila/AGENTS.md)
|
||
|
||
### 14. [Moritz Health & Nutrition Web App](./projects/moritz/AGENTS.md) (`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](./projects/moritz/AGENTS.md)
|
||
|
||
### 15. [Shelly Taupunktlüfter](./projects/shelly_taupunktluefter/AGENTS.md) (`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](./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](./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`
|