# Architecture Decision Records (ADRs)

This directory documents the key architectural decisions made within the **Infrapuzzle** monorepo and its associated workloads (Kubernetes, OpenClaw AI agent, networking, DNS, and smart home systems).

We follow the [Markdown Architectural Decision Records (MADR)](https://adr.github.io/madr/) format to capture intentional technical decisions, their context, considered options, trade-offs, and consequences.

---

## 📋 Record Index

| ADR | Title | Status | Date | Area |
| :--- | :--- | :---: | :---: | :--- |
| [**0001**](0001-hybrid-mcp-tool-search-and-subagents.md) | **Hybrid MCP Tool Search and Subagent Delegation for AI Agents** | `accepted` | 2026-09-12 | OpenClaw / AI / MCP |
| [**0002**](0002-openclaw-model-selection-tiering-and-economics.md) | **OpenClaw Multi-Tier Model Selection, Latency Optimization, and Inference Economics** | `proposed` | 2026-09-13 | OpenClaw / AI / Models |
| [**0003**](0003-everything-as-code-and-reproducible-infrastructure.md) | **Everything as Code (EaC) and Reproducible Declarative Infrastructure** | `accepted` | 2026-09-17 | Architecture / Monorepo / EaC |
| [**0004**](0004-structured-personal-data-datastore.md) | **Structured Personal Data Layer (DuckDB + JSONL in Knowledge Wiki)** | `accepted` | 2026-10-06 | OpenClaw / Data / Storage |
| [**0005**](0005-personal-data-isolation-and-authentik-boundary.md) | **Personal Data Isolation, Authentik Authentication Boundaries, and Hosting Segregation** | `accepted` | 2026-10-11 | Security / Storage / Authentik |

---

## ✍️ How to Create a New ADR

1. Copy the template structure into a new numbered markdown file:
   ```bash
   docs/adr/000X-short-title-in-kebab-case.md
   ```
2. Include the YAML frontmatter:
   ```yaml
   ---
   status: "proposed | accepted | superseded | deprecated"
   date: YYYY-MM-DD
   decision-makers: ["Moritz Graf", "Antigravity"]
   consulted: []
   informed: []
   ---
   ```
3. Clearly define:
   - **Context & Problem Statement** (Why was this decision needed?)
   - **Decision Drivers** (Constraints, costs, token limits, latency, maintainability)
   - **Considered Options** (Alternatives evaluated)
   - **Decision Outcome** (Chosen path with justification)
   - **Consequences** (Positive effects, negative trade-offs, follow-up actions)
4. Add the new record to the table in this `README.md`.