chore: scaffold M0 — repo structure, ADRs, dev environment, pre-merge checklist

2026-08-02 10:26:49 +02:00
commit 581191e93a
20 changed files with 781 additions and 0 deletions
@@ -0,0 +1,26 @@
+# ADR-002: Docs → Qdrant sync strategy
+
+**Status:** Accepted (default recommendation — flag in review if you want polling instead)
+**Date:** 2026-08-02
+
+## Context
+
+The Knowledge Ingestion Service (founding strategy, Section 3) needs to keep Qdrant's embeddings in sync with source documents (Docker Compose files, Markdown docs, configs) living in Gitea. Two options:
+
+- **Polling:** the Ingestion Service periodically checks Gitea for changes and re-syncs.
+- **Webhook:** Gitea pushes a notification to the Ingestion Service on every relevant commit, triggering an immediate re-sync.
+
+Polling is simpler to build first (no inbound endpoint, no webhook secret to manage) but introduces staleness by design — the exact problem flagged in the founding strategy, Section 1.5 ("knowledge freshness" as a first-class requirement). Webhook-based sync is barely more work at this scale (Gitea supports repository webhooks natively) and directly serves the freshness requirement.
+
+## Decision
+
+Use a **Gitea webhook** on relevant repositories, calling a Backend API endpoint that triggers re-ingestion of the changed files. Every ingested chunk stores a `last_synced_at` timestamp sourced from the commit, surfaced in every Knowledge Agent answer (per Section 1.5).
+
+A lightweight periodic reconciliation job (e.g. once daily) remains as a safety net in case a webhook delivery is missed — this is not the primary mechanism, just a backstop.
+
+## Consequences
+
+- Requires a webhook secret to be configured and kept out of version control (`.env`, never committed).
+- Ingestion Service needs an inbound endpoint reachable from Gitea — trivial on the same homelab network, worth remembering if Gitea and the platform ever live on separate networks.
+- Freshness timestamps become a real, enforceable product feature from day one rather than an afterthought.
+- If webhook reliability becomes a problem in practice, the daily reconciliation job already covers the failure mode — no redesign needed, just tune its frequency.