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.
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 optionallyentity_id. The platform turns them into the collection identifierapp_{application}_instance_{instance}[_entity_{entity}], for exampleapp_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,COMPLETEDorFAILED. OnlyCOMPLETEDfiles 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 whosereference_indexis2. 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.