Skip to content

Architecture

This section documents RAGhelm's architecture, technology choices, and hard-to-reverse decisions. It is intended for users, operators, and coding agents who need to understand what exists today before changing the system.

Start here

Question Read
What are the major runtime components and data flows? System Overview
What technology choices does the project use and why? Technology Choices
How does Pinecone reference backend indexing and namespace management work? Pinecone Reference Backend Indexer
What architecture decisions have been accepted or proposed? Architecture Decision Records

System shape

RAGhelm-owned reference runtime
  -> QueryPipeline
  -> eval evidence
  -> RAGRunManifest
  -> ReadinessScorecard
  -> deterministic release gates

External systems under test
  -> TargetAdapter
  -> normalized evidence
  -> RAGRunManifest
  -> ReadinessScorecard
  -> deterministic release gates

The first architecture question is not which vector database answers a query. It is whether a private RAG/agent release can ship, which evidence proves that decision, and which evidence is safe to publish.

The implemented system has three important user-facing surfaces:

  1. Python CLI: python -m raghelm ingest ... and python -m raghelm eval ...
  2. Python FastAPI query API: raghelm/api/server.py
  3. React/Vite dashboard: packages/dashboard

There is also a lightweight TypeScript Fastify package in packages/api; today it is a separate Node boundary and not the canonical implemented RAG query API.

Architecture Decision Records

ADRs capture important architectural decisions with context, tradeoffs, and consequences. Add or update an ADR when a change is hard to reverse, changes production behavior, or constrains future work.

How to write a new ADR

  1. Copy decisions/000-template.md.
  2. Rename it to NNN-short-title.md.
  3. Document the decision, tradeoffs, consequences, and rollback/risk notes.
  4. Update this index and mkdocs.yml navigation.

Priority and scope order

ADR numbers are ordered by product/architecture priority and scope. Broad product-boundary and evidence-contract decisions come first; backend-specific reference-runtime decisions, including Pinecone, follow the higher-scope decisions they depend on.

Active decisions

# Title Decision status Implementation status Applies to
001 Product Architecture Spine for Private RAGOps Release Control Accepted Partial Reference runtime, external targets, enterprise/BYOC
002 Release Readiness Scorecard and RAGRunManifest as Core Product Objects Accepted Partial Reference runtime, external targets
003 Security and Compliance Boundary Accepted Not started Reference runtime, external targets, enterprise/BYOC
004 Embedding Model Strategy Accepted Partial Reference runtime
005 Pinecone Reference Backend Namespace Strategy Accepted, amended by ADR-004 and ADR-013 Partial RAGhelm Pinecone reference backend
006 Canonical Runtime and API Boundary Accepted Partial Reference runtime, enterprise/BYOC
007 Shared QueryPipeline as Production-Eval Source of Truth Accepted Contract frozen Reference runtime
008 Readiness Gate Policy and Failure Semantics Accepted Contract frozen Reference runtime, external targets
009 RAGRunManifest Schema and Artifact Lifecycle Accepted Contract frozen; partial artifacts Reference runtime, external targets
010 Production Claims, Badges, and Public Proof Source of Truth Accepted Not started Reference runtime, future
011 Retrieval Routing, Hybrid Search, and Reranking Policy Accepted Not started Reference runtime
012 Model Provider Abstraction Boundary Accepted Not started Reference runtime
013 External Target Adapters and Vector Backend Boundary Accepted Contract frozen External targets, reference runtime, enterprise/BYOC
014 Native JSON Observability and Future OpenTelemetry Interoperability Accepted Contract frozen; partial artifacts Reference runtime, external targets, future
015 Persistence Store for Release-Control History Accepted Not started Reference runtime, enterprise/BYOC
016 Agent Runtime Scope, Tool Contract, and Side-Effect Safety Accepted Contract frozen Reference runtime, external targets
017 Memory and Tenant Isolation Boundary Accepted Not started Reference runtime, external targets, enterprise/BYOC
018 Human Review and Release Override Model Accepted Not started Reference runtime, enterprise/BYOC
019 Async Execution and Worker Queue Accepted Not started Reference runtime, future
020 Deployment and Private-Cloud/BYOC Architecture Accepted Not started Enterprise/BYOC, reference runtime
021 Open-Core and Commercial Boundary Accepted Not started Enterprise/BYOC, future

Documentation expectations

Every architecture-impacting change should leave users with:

  • the technology choice and rationale
  • the user-facing command or endpoint, if applicable
  • the production/local/dry-run behavior
  • related ADR links
  • verification commands
  • known limitations or non-goals

Why this format

  • It exposes current architecture without requiring users to inspect source code first.
  • It keeps technology choices and ADRs discoverable from the docs navigation.
  • It gives coding agents a stable place to check before making architectural changes.

Maintained by: Core team
Last updated: 2026-06-16