Skip to content

Concepts

Architecture

A default RAG Platform installation runs these services. Only RAG Web is reachable from outside. Everything else runs on an internal network.

Service Component Role
web-gateway RAG Web The public HTTP API. Authenticates API keys, resolves the tenant, forwards requests to RAG System and to the inference provider
gateway-database PostgreSQL Stores tenants and API keys
web-gateway-migrations RAG Web One-shot job that applies database migrations to the gateway database
valkey Valkey Cache for resolved API keys
api-gateway RAG System Internal API: accepts uploads, runs retrieval and augmentation
ingestion RAG System Processes uploaded files into chunks for the rag-database
dlq-consumer RAG System Handles files that failed the ingestion process
rabbitmq RabbitMQ Queues files between api-gateway, ingestion and dlq-consumer
rag-database RAG System (PostgreSQL with pgvector and pg_search) Collections, files, chunks (vector-db)
rag-database-migrations RAG System One-shot job that applies migrations to the RAG database

The platform does not host models, instead it requires an OpenAI-compatible inference provider, such as KI:Connect.

Below is a diagram displaying the architecture. Click to enlarge it.

An architecture diagram showing the relationship between the services. An architecture diagram showing the relationship between the services (but in darkmode).

Glossary

Tenant
One organization or application whose content is isolated from every other tenant. Operators create tenants in the gateway database.
API key
The credential of a client application, sent as a bearer token. Each key belongs to exactly one tenant, and the key alone determines which tenant a request acts as.
Collection
A named set of files inside one tenant, and the unit of retrieval. Uploads address a collection with integers: application_id, instance_id, and optionally entity_id. The platform turns them into the collection identifier app_{application}_instance_{instance}[_entity_{entity}], for example app_1_instance_1_entity_1. Two tenants can use the same identifier without sharing data.
File status
The ingestion state of an uploaded file: PENDING, PROCESSING, COMPLETED or FAILED. Only COMPLETED files are searchable.
Chunk
A piece of a file's text with its embedding and metadata, such as page numbers. Retrieval returns chunks.
Augmentation
Retrieval plus prompt building. The platform finds the chunks relevant to the last user message and rewrites that message so that it contains the sources and instructions on how to cite them.
Citation marker
A token such as [cit-2] in a generated answer. It refers to the retrieved chunk whose reference_index is 2. See Streaming and citations.
Product version
The version of the RAG Platform as a whole, set by a rag-docker release, for example 1.1.0. These docs are versioned by product version.
Component version
The version of RAG Web or RAG System. Each product version pins one component version each. See Versioning and compatibility.