Architecture

The system is split by responsibility.

HARP owns evidence retrieval, citations, and evals. OpenRAG owns optional semantic retrieval. MCP provides constrained read-only agent access. Nero-Camp owns task state and human decision history. LiteLLM provides model routing in the wider architecture. Synthetic Monitoring normalizes and deduplicates signals before downstream triage.

The fallback path is part of the architecture: if semantic or model services are unavailable, HARP still returns cited BM25 evidence.

End-to-end flow

From signal to operational memory.

Observe

Uptime Kuma synthetic probes (outside-in) or Prometheus/Alertmanager alerts (inside-out).

Normalize

Synthetic Monitoring gateway maps both signal types into a shared alert contract.

Deduplicate

SQLite-backed queue deduplicates active incidents by fingerprint.

Retrieve

HARP searches BM25 and optional OpenRAG semantic index.

Ground

RRF merge produces cited sources, snippets, confidence, and gaps.

Present for human review

Evidence pack and Nero-Camp task surface to the operator.

Record the outcome

Human decision, approval state, and closeout are recorded in Nero-Camp.

Add to operational knowledge

RCA or runbook update becomes future retrieval evidence.

Module Map

What each component does and does not do.

HARP

Evidence engine

Indexes runbooks, RCAs, session logs, monitoring docs, and generated evidence packs. Exposes FastAPI endpoints and read-only MCP tools. Falls back to cited BM25 when semantic services are unavailable.

Owns: Search, evidence packs, citations, evidence rendering, evals, policy labels, MCP surface.

Does not own: Task approval, live mutation, autonomous remediation.

OpenRAG

Semantic retrieval

Optional semantic layer for symptom-language discovery beyond exact keywords. HARP mediates access and falls back to BM25 if OpenRAG is down.

Owns: Vector search, embeddings, semantic ranking.

Does not own: HARP policy, Nero workflow state, final decisions.

MCP

Agent interface

Lets AI clients ask HARP for tools, resources, and prompt templates through a standard interface. MCP interface version 0.5.0.

Owns: The read-only access contract for AI clients.

Does not own: Shell, Git writes, kubectl mutation, remediation.

Nero-Camp

Control plane

Consumes HARP evidence as citations and advisory metadata. Keeps source records, timelines, approvals, and human decisions.

Owns: Task state, approval, audit timeline, operator decision.

Does not own: Assuming HARP advice is executable action.

LiteLLM

Model gateway

Provides an OpenAI-compatible gateway for local or cloud models. The read-only AI remediation agent has a verified LiteLLM/Mistral path. HARP core retrieval does not require LiteLLM.

Owns: Model routing and provider abstraction in the wider reliability architecture.

Does not own: Retrieval, approvals, task state, source citations.

Synthetic Monitoring

Signal gateway

Universal incident gateway: outside-in probes and inside-out cluster alerts both feed a shared downstream triage pipeline.

Owns: Alert normalization, deduplication, webhook ingestion from Uptime Kuma and Alertmanager.

Does not own: Evidence scoring, policy, approval state, autonomous remediation.

n8n

Optional workflow glue

Deployed and available in the homelab for optional workflow automation. Not part of the currently verified HARP critical path.

Owns: Webhook fan-out, schedules, notification routing, low-risk event glue.

Does not own: Evidence scoring, policy, approval state, core retrieval path.

Safety Boundary

The read-only line is the architecture.

Layer	Allowed	Blocked	Reason
MCP	Search, hybrid search, source preview, triage rendering.	Shell, Git write, kubectl mutation, evidence writes.	Agents need context, not production power.
HARP	Evidence rendering, citation ranking, policy labels, evals.	Autonomous remediation and source-of-truth task decisions.	HARP is memory and evidence, not the operator.
Nero-Camp	Task state, source records, timeline, approval, closeout.	Treating HARP output as executable authority.	Nero records the human decision.
OpenRAG	Semantic indexing and retrieval.	Direct agent access that bypasses HARP policy.	HARP mediates retrieval and fallback behavior.
LiteLLM	Classification and summarization when policy allows.	Replacing citations or final decisions.	Model output must remain grounded and governed.
Synthetic Monitoring	Signal ingestion, normalization, deduplication.	Evidence retrieval, approval, remediation.	Gateway normalizes signals; HARP retrieves evidence.