A RAG demo is relatively easy to build.

Load a few documents, split them into chunks, generate embeddings, store those vectors, retrieve the most relevant passages, and ask a language model to produce an answer. With a small dataset and a carefully chosen question, the result can look impressive.

The difficult part starts when that demo needs to become a system that other teams can depend on.

Real-world enterprise retrieval systems need to deal with questions that are rarely addressed in tutorials:

• Can users retrieve only the information they are authorized to see?
• Can someone ask a question in one language and retrieve reliable answers written in another?
• Can different use cases use different retrieval profiles without rewriting application code?
• Can domain logic evolve without being coupled to a specific search engine, embedding provider, or document parser?
• What happens when document ingestion fails halfway through?
• Can we explain why a result was retrieved, measure its quality, and improve it systematically?

These are architecture and software engineering questions as much as they are AI questions.

I have been exploring these challenges in BeyondRAG, an evolving Python-based retrieval project built around Elasticsearch and configurable RAG capabilities. Rather than treating it as a finished framework, I use it as a practical engineering exercise: take a working retrieval implementation and improve the boundaries, configuration, and responsibilities that matter when moving beyond a proof of concept.

This article walks through the architectural evolution, the trade-offs, and the reasoning behind each decision.

The central premise: Production-oriented RAG is not just about picking a larger model or tweaking a prompt. It is about building a retrieval engine whose behavior, dependencies, security boundaries, and failure modes can be understood, tested, and evolved.

1. The Gap Between a RAG Demo and a Dependable System

A basic RAG pipeline typically follows five linear steps:

1. Receive a user query.
2. Convert the query into an embedding vector.
3. Perform an unconstrained top-K vector similarity search.
4. Inject retrieved chunks into a prompt template.
5. Call an LLM to generate an answer.

That is a great proof of concept. But this naive pipeline hides critical assumptions inside implementation details:

• Rigid retrieval parameters: Fixed top-K limits, fixed chunk sizes, and hardcoded similarity metrics.
• Leaky abstractions: The core service orchestrating the workflow often directly instantiates Elasticsearch clients, Ollama or OpenAI SDKs, PyPDF extractors, and embedding models.
• Single-user assumptions: No isolation between departments, roles, or tenants.

In an enterprise, one size never fits all:

• A Customer Support Bot prioritizes broad recall over a large corpus.
• An Executive Assistant demands high precision and concise answers over a tight set of high-confidence policy memos.
• A Compliance Auditor requires deterministic, verbatim source citations with zero hallucination tolerance.

These are not separate applications; they are different retrieval profiles over the same organizational knowledge base.

Furthermore, access control cannot be an afterthought. If an unauthorized document enters an LLM context window, that is not a ranking error—it is a critical security failure.

2. Decouple Domain Behavior from Infrastructure

The first architectural refactor in BeyondRAG was applying Dependency Inversion (Hexagonal / Ports and Adapters architecture) to isolate domain logic from concrete infrastructure.

In early prototypes, it is tempting to let the central knowledge base service directly call elasticsearch.Elasticsearch, google.genai, or ollama. While fast to write, this binds your business logic to third-party APIs, making unit testing slow, brittle, and dependent on live external services.

Inverting the Dependencies

We separated the retrieval engine into explicit domain interfaces (Protocols) and pluggable infrastructure adapters:

• Domain Layer (src/rag/ports.py): Pure Python type contracts defining what the system needs.
• Infrastructure Adapters: Concrete implementations for Elasticsearch 8.15, Ollama, Gemini, PyPDF, and Markdown.
• Service Facade (src/rag/service.py): Thin coordinator delegating strictly to injected port implementations.

flowchart TD
    subgraph AppLayer["Application & API Layer"]
        API["FastAPI Endpoints<br/>(/api/chat, /api/upload)"]
        CLI["CLI & Benchmarks"]
    end

    subgraph DomainOrch["Domain Orchestration"]
        Facade["RBACKnowledgeBaseService (Facade)"]
        Ingest["Document Ingestor"]
        Retriever["Hybrid Retriever"]
        Synth["Answer Synthesizer"]
    end

    subgraph DomainPorts["Domain Port Protocols (src/rag/ports.py)"]
        P_Search["SearchIndexPort"]
        P_Embed["EmbeddingProviderPort"]
        P_LLM["LLMPort"]
        P_Extract["DocumentExtractorPort"]
        P_ACL["ACLPolicyPort"]
    end

    subgraph InfraAdapters["Infrastructure Adapters"]
        A_ES["Elasticsearch 8.15 Adapter<br/>(int8_hnsw + BM25)"]
        A_Ollama["Ollama / Gemini Adapter"]
        A_Embed["Embedding Providers<br/>(FeatureHash / Ollama / Google)"]
        A_PDF["PyPDF & PlainText Parsers"]
    end

    API --> Facade
    CLI --> Facade
    Facade --> Ingest
    Facade --> Retriever
    Facade --> Synth

    Ingest --> DomainPorts
    Retriever --> DomainPorts
    Synth --> DomainPorts

    P_Search -.implements.- A_ES
    P_Embed -.implements.- A_Embed
    P_LLM -.implements.- A_Ollama
    P_Extract -.implements.- A_PDF

Strongly Typed Domain Protocols

Rather than importing client libraries, domain services depend on pure Python protocols:

# src/rag/ports.py
from typing import Protocol, List, Dict, Any, Optional

class EmbeddingProviderPort(Protocol):
    """Domain contract for vector generation."""
    @property
    def dimensions(self) -> int: ...
    
    def embed_query(self, text: str) -> List[float]: ...
    def embed_documents(self, texts: List[str]) -> List[List[float]]: ...

class SearchIndexPort(Protocol):
    """Domain contract for search engine persistence & retrieval."""
    def search(
        self,
        query_text: str,
        query_vector: List[float],
        acl_filter: List[str],
        top_k: int,
    ) -> List[Dict[str, Any]]: ...

Why This Matters

1. Deterministic Testing: We can run full end-to-end integration tests using in-memory mock adapters without starting Docker, Elasticsearch, or an LLM daemon.
2. Zero Vendor Lock-in: Swapping Elasticsearch for OpenSearch or switching embedding providers requires implementing an adapter—the core ingestion and ACL logic remains untouched.
3. Clean Code Boundaries: Search query DSL belongs inside the search adapter; document parsing belongs in the extractor; retrieval policy belongs in the domain.

3. Single Responsibility: Breaking the God Service

Dependency inversion alone does not guarantee maintainability. A service can depend on interfaces and still be a bloated "God Class" that does too much.

In BeyondRAG, we split the monolithic knowledge base service into six single-responsibility components:

The central RBACKnowledgeBaseService remains as a lightweight facade that coordinates these components, providing a single clean API to web controllers and background workers.

4. Configurable Retrieval Profiles

Hardcoding top_k = 4 and min_score = 0.7 across an entire application forces different use cases to make painful compromises.

BeyondRAG introduces Retrieval Profiles to make retrieval behavior an explicit, validated configuration:

# config/retrieval_profiles.yaml
profiles:
  precision:
    top_k: 2
    min_should_match: "75%"
    hybrid_dense_boost: 2.5
    hybrid_sparse_boost: 1.0
    synthesis_mode: "strict_grounded"
    
  high_recall:
    top_k: 8
    min_should_match: "40%"
    hybrid_dense_boost: 1.0
    hybrid_sparse_boost: 2.0
    num_candidates_multiplier: 5
    synthesis_mode: "comprehensive"
    
  executive_summary:
    top_k: 3
    min_should_match: "60%"
    hybrid_dense_boost: 2.0
    hybrid_sparse_boost: 1.2
    synthesis_mode: "fast_bullets"

Precedence Resolution

Configurability only works if precedence is predictable. BeyondRAG enforces a strict resolution hierarchy:

Default Profile (Baseline)
    └──> Named Profile Override (e.g., 'precision')
            └──> Request-Level Override (e.g., per-query top_k)

Every parameter is validated at startup so typos fail fast rather than silently falling back to defaults.

5. Chunking is a Retrieval Decision, Not a Preprocessing Detail

Chunking is often treated as simple text splitting (text[:500]). In practice, chunking determines the granular boundary of semantic relevance.

• Chunks that are too large: Dilute relevance with unrelated paragraphs and exhaust token context.
• Chunks that are too small: Fragment thoughts, causing the LLM to misinterpret incomplete context.

BeyondRAG supports pluggable, deterministic chunking strategies:

• Sliding Window: Fixed token windows with configurable overlap for dense unstructured text.
• Paragraph-Oriented: Preserves natural section headings and narrative boundaries.
• Sentence-Oriented: Chunks across grammatical clause boundaries, preventing sentence truncation.

The Token vs. Character Distinction

A common bug in multilingual RAG is defining chunk size in characters. In English, 500 characters is roughly 100 words (130 tokens). In Chinese, 500 characters can represent ~400 dense tokens! Chunk size must be measured in tokens using a tokenizer appropriate for your target embedding model.

6. Access Control Belongs in the Storage Engine (Pre-Filtering)

In enterprise RAG, authorization is a core retrieval constraint, not a prompt instruction.

Why Naive Python Post-Filtering Drops Recall to 0%

The most common architectural mistake in early RAG systems is post-filtering: running an unconstrained vector search first, then dropping unauthorized chunks in application code:

# ❌ DANGEROUS ANTI-PATTERN: Naive Python Post-Filtering
raw_hits = vector_db.search(query_vector, top_k=5)
authorized_hits = [hit for hit in raw_hits if user.can_access(hit.role)]

When restricted documents (such as confidential M&A memos or executive salary sheets) have high semantic similarity to a question, they saturate all K candidate slots in the vector graph. When Python discards them afterward, the user receives 0 results (0% recall)—even though perfectly valid public documents exist in the index!

flowchart TD
    subgraph Naive["❌ Naive RAG: Post-Filtering"]
        N1["User Query: 'Minimum cash reserve buffer?'"] --> N2["Unconstrained Top-5 kNN Search"]
        N2 --> N3["Top-5 Slots Filled by Restricted Finance Memos"]
        N3 --> N4["Python Checks Role: User is Public-Only"]
        N4 --> N5["Python Discards All 5 Hits<br/>❌ 0% Recall Starvation (Zero Results Returned)"]
    end

    subgraph Beyond["✅ BeyondRAG: Storage-Engine Pre-Filtering"]
        B1["User Query + Active Roles: ['__public__']"] --> B2["Lucene Index Pre-Filters by acl_tags"]
        B2 --> B3["kNN Graph Explores Only Authorized Nodes"]
        B3 --> B4["Returns Authorized Public Documents<br/>✅ 100% Recall & Zero Data Leakage"]
    end

The Solution: Lucene-Level Pre-Filtering

In BeyondRAG, access control is enforced directly inside the Elasticsearch 8.15 query engine:

# src/rag/retriever.py
acl_filter_clause = {"terms": {"acl_tags": effective_acl_filter}}

es_query = {
    "size": profile.top_k,
    "query": {
        "bool": {
            "should": [
                {"match": {"content": {"query": expanded_query, "boost": 2.0}}},
                {"match": {"title": {"query": expanded_query, "boost": 1.2}}}
            ],
            "filter": [acl_filter_clause]  # <-- Lexical pre-filter
        }
    },
    "knn": {
        "field": "embedding",
        "query_vector": query_vector,
        "k": profile.top_k,
        "num_candidates": profile.num_candidates,
        "filter": acl_filter_clause        # <-- Vector HNSW pre-filter
    }
}

Because permissions are evaluated during graph traversal, unauthorized content never enters memory and cannot starve authorized results.

7. Cross-Lingual Retrieval Needs Explicit Language Boundaries

In global organizations, policy documents are frequently written in English, while employees ask questions in Traditional or Simplified Chinese, Dutch, or German:

• Uploaded English PDF (HK_Treasury_FX_Liquidity_Policy_Q4.pdf):

  "The Group Treasury division must maintain an intraday minimum unencumbered cash reserve of HKD 450,000,000..."

• Employee Query in Chinese:

  「最低港元現金儲備緩衝是多少？外匯遠期合約限額是多少？」

Standard lexical search (BM25) fails completely because there is zero character overlap between Chinese characters and English words.

BeyondRAG separates cross-lingual handling into distinct responsibilities:

1. Language Detection: Identifies script and language without mistaking accented Latin characters for foreign scripts.
2. Dynamic Ingestion-Time Concept Extraction: Whenever a PDF is uploaded, a local LLM extracts key domain concepts and generates bilingual English ↔ Chinese triggers.
3. Query Expansion & Semantic Projection: Projects queries into a shared semantic representation, preserving original search terms while providing bilingual coverage.

When a Chinese query is executed, BeyondRAG retrieves the exact English policy passage and cites the HKD 450,000,000 reserve in milliseconds.

8. Embedding Configuration is Part of the Index Contract

Embedding models cannot be treated as interchangeable black boxes.

Vector dimensions, normalization algorithms (L2 vs. cosine), distance metrics (dot product, Euclidean, cosine), and token truncation limits constitute an immutable contract with your search index.

If an application silently switches from a 256-dimensional model to a 1536-dimensional model, or changes normalization strategies, vector math breaks.

BeyondRAG introduces an Embedding Manifest stored alongside the index metadata:

{
  "manifest_version": "1.0",
  "provider": "ollama",
  "model_name": "qwen2.5:1.5b",
  "dimensions": 256,
  "metric": "cosine",
  "normalization": "l2",
  "created_at": "2026-10-30T16:12:12Z"
}

If an incoming document or query embedding does not match the index manifest, the engine fails explicitly and immediately rather than generating corrupt vector scores.

9. Ingestion Reliability: Idempotency & Lifecycle States

In production, documents are updated, re-indexed, and occasionally encounter corrupted pages. A dependable ingestion engine requires explicit lifecycle states:

[PENDING] ──> [PROCESSING] ──> [INDEXED]
                     │
                     └──> [FAILED] (with rollback)

Key reliability patterns implemented in BeyondRAG:

• Deterministic Document IDs: Document IDs are derived from a cryptographic hash of content and tenant metadata (doc-sha256), preventing duplicate chunk creation on retry.
• Atomic Rollback: If bulk indexing fails midway, previously indexed chunks for that document are automatically cleaned up.
• Zero Orphaned Uploads: Uploaded binary files are bound to the document lifecycle.

10. Automated Benchmarks: Putting Architecture to the Test

To verify that storage-engine pre-filtering actually solves recall starvation, we run an automated benchmark suite (benchmark_rbac.py) comparing naive post-filtering against BeyondRAG across 20 iterations:

11. Run the Interactive Sandbox Locally

You can clone and run the complete containerized BeyondRAG application with the Catppuccin Mocha interface in one command:

git clone https://github.com/metemertkan/BeyondRAG.git
cd BeyondRAG
docker compose up -d --build

Access the dashboard at http://localhost:8090 to:

1. Upload & Tag PDFs: Upload an English Finance or Operations PDF and assign RBAC tags.
2. Test Public Blocking: Run a Chinese query as Public Only to see the live 🔒 403 Access Blocked card.
3. Switch Roles: Toggle to Finance Role or Operation Role and watch the English document unlock and answer in Chinese with sub-10ms latency.

Summary & What’s Next

Building a RAG proof of concept teaches you how to connect an LLM to a vector database.

Building a dependable retrieval engine teaches you how to manage architectural boundaries:

• Decouple domain logic from infrastructure using ports and protocols.
• Push access control down into the storage engine to eliminate recall starvation.
• Separate cross-lingual responsibilities instead of relying on opaque translation.
• Treat embedding metadata as an immutable index contract.

In Episode #02 of Beyond a PoC, we will take this foundation further with a deep dive into Multi-Column Document Ingestion, Financial Table Parsing, and Native Multilingual Embedding Models (bge-m3).

👉 Repository: https://github.com/metemertkan/BeyondRAG

What has been the most frustrating architectural challenge in your production RAG deployments—authorization, cross-lingual search, or ingestion reliability? Let's discuss in the comments below.