Skip to content
Arxo Arxo

RAG Architecture

RAG Architecture

Section titled “RAG Architecture”

This guide shows an end-to-end workflow for improving rag_architecture health in production RAG systems.

Workflow

Section titled “Workflow”
  1. Run a RAG-focused audit.
  2. Triage findings by risk domain and centrality impact.
  3. Apply targeted remediation.
  4. Enforce policy gates in CI.
  5. Prevent regressions with baseline checks.

1) Run a RAG Audit

Section titled “1) Run a RAG Audit”
Terminal window
# Focused RAG metric
arxo analyze --path . --metric rag_architecture --format json
Terminal window
# RAG preset (rag_architecture + llm_integration)
arxo analyze --path . --preset rag --format json

For engine-aligned weighting, run rag_architecture with centrality enabled in config:

metrics:
  - id: centrality
  - id: rag_architecture

2) Triage Findings

Section titled “2) Triage Findings”

Prioritize in this order:

  1. retrieval_scope_filter_gap, prompt_injection_guard_gap, retrieved_content_sanitization_gap, retrieval_trust_boundary_gap
  2. tenant_isolation_risk, embedding_poisoning_guard_gap, claim_support_gap
  3. retrieval_latency_risk, index_freshness_risk, cache_layer_gap, ingestion_resilience_gap, retrieval_thresholding_gap, contextual_retrieval_gap
  4. context_budget_gap, reranking_gap, query_planning_gap, retrieval_adaptation_gap, retrieval_topology_maturity_gap
  5. eval_harness_gap, eval_metric_coverage_gap, grounding_citation_gap, citation_precision_gap, citation_coverage_gap, answerability_gate_gap

Then inspect composite movement:

  • rag_architecture.retrieval_readiness
  • rag_architecture.safety_readiness
  • rag_architecture.evaluation_readiness
  • rag_architecture.overall_health

3) Apply Fixes by Track

Section titled “3) Apply Fixes by Track”
  • Safety track: scoped retrieval filters, prompt-injection protections, sanitization, and trust boundaries.
  • Freshness/reliability track: source versioning, reindex triggers, embedding version pinning, resilient ingestion.
  • Quality track: reranking, contextual retrieval, thresholding, claim support, citation precision/coverage.
  • Performance track: budgeted context assembly, bounded retrieval fanout, timeout/circuit-breaker controls.

Use the Remediation Playbook for fix-by-metric guidance.

4) Enforce in CI

Section titled “4) Enforce in CI”

Use profiles from Policy and CI Gates.

Terminal window
arxo analyze --path . --preset rag --config arxo.yml --fail-fast

Recommended rollout:

  1. Start with pragmatic warning thresholds.
  2. Fix recurring high-severity findings in central modules.
  3. Promote strict gates to error after stability.

5) Baseline and Monorepo Rollout

Section titled “5) Baseline and Monorepo Rollout”
  • Enable baseline no-regression checks against origin/main.
  • Start with one critical service/workspace.
  • Expand to additional workspaces once score trends stabilize.
Section titled “Related Reading”