Deployment
The same runtime pieces drive every deployment. This page describes that architecture once, then shows how it is configured for the supported development setup and for the production topology it is designed for — which is not yet supported in this release.
Architecture
Pelorus separates the write/control plane from the read path. The engine owns ingestion and is the only writer to the stores; the serving API answers queries by reading the vector store directly. The database is the system of record, and the vector store is a rebuildable projection of it.
Engine
The control plane and the only writer to the stores. All ingestion, embedding, indexing, clustering, and Extract curation go through it.
Serving API
The read path. Embeds the query, searches the vector store, applies Pelorus filtering, and returns results. Lightweight and stateless.
Admin UI
Connects to the engine over its management API to register datasets, run queries, and curate Extracts. Always an API client of the engine.
Control store (DB)
The system of record: Extract bodies, source text, clusters, demand, and usage history.
Vector store
The searchable index. A rebuildable projection of the database — it can be regenerated from the system of record at any time.
Models
An embedding model and an extract LLM, pinned so stored vectors and query embeddings share one embedding space.
Two pieces are designed as pluggable seams — the RAG Connector and the vector store. The connector is the interface Pelorus reads a retrieval system through: retrieve for a query, enumerate the corpus, fetch by id. It is deliberately read-only — it never ingests, clears, or writes a corpus, because it points at a system someone else owns. These extension interfaces are early and may change.
Development
The developer release runs every component on one machine. The vector store and database are embedded for convenience, so nothing external is required beyond your model providers.
Engine + Admin UI
Run locally; the Admin UI connects to the engine's management API.
Embedded stores
An embedded vector store plus a local SQLite control database. No external services to run.
Pipeline + Models
The built-in RAG pipeline, with your configured embedding model and extract LLM.
pip install -e ".[admin,mcp]"
# Start the engine and Admin UI together.
# macOS / Linux
./start.sh
# Windows
start.batThe single-command start script is the supported deployment for this developer preview. Attaching the console to a separately-run engine with pelorus-admin --connect works but is experimental and unsupported for now.
The embedded vector store, the local SQLite database, and the local Admin UI are developer conveniences. In the production topology, each is replaced or relocated through the same interfaces.
Production
In production the components separate onto their own tiers, but their roles are unchanged. The engine stays the only writer; the read path scales independently.
Serving tier
The serving API runs as one instance or a stateless cluster behind a load balancer, scaling with read traffic.
Remote vector store
A supported remote vector store holds the index, shared across the serving tier.
Control store
SQLite by default, or a remote database for backup and write concurrency.
System of record
The database stays authoritative; the vector store is a rebuildable projection. It can be regenerated from the database at any time, which is what makes recovery and migration between stores possible.
Promotion
Because the index rebuilds from the database, a dataset can be built and curated in one environment and published to a production serving store during an update window. All updates still flow through the engine.