27 lines
2.0 KiB
Markdown
27 lines
2.0 KiB
Markdown
# 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.
|