Services
Runtime services used by OrcAI.
OrcAI is a multi-service application. The app and workers are separate processes that share the same backing services.
Service map
| Service | Role | Required for |
|---|---|---|
| App | UI, authentication, API routes, workflows | All user-facing use |
| Workers | Background jobs and scheduled maintenance | Asset preparation, email and quota pools |
| PostgreSQL | Relational application data | Core persistence |
| SeaweedFS/S3 | Uploaded and processed files | Library |
| Qdrant | Vector indexes | Retrieval |
| SpiceDB | Authorisation relationships | Access control |
| AI endpoint | Embeddings | Indexing and retrieval |
App
The main app is a Bun/TanStack Start application. It serves the user interface, authentication, oRPC API routes, and application workflows. It also works the data export queue, because building an export's chat transcripts needs the app's own code.
In Docker Compose, the service name is app. Its healthcheck calls /api/health, which reports whether PostgreSQL and SpiceDB answer.
Web (docs)
The repository Compose stack also includes a web service for the documentation website. The app reads the docs from it, through WEB_INTERNAL_URL, when the OrcAI Assistant answers questions about OrcAI.
Workers
Workers run background jobs for asset preparation (including indexing), metadata suggestions, quota pool period rollover and releasing the quota pool reservations of replies that never ended. They send every email OrcAI writes, so without them no invitation or password reset arrives. They also create the data export queues, which the app works, delete expired export archives and clean up old activity entries. Workers must be running for uploaded assets to become searchable. Operations lists the jobs.
PostgreSQL
PostgreSQL stores application data. The Compose stack uses the pgvector/pgvector:0.8.7-pg17 image, although retrieval vectors are stored in Qdrant.
SeaweedFS or S3-compatible storage
Uploaded files and processed artifacts are stored in S3-compatible object storage. Compose runs SeaweedFS in single-container mode, which creates the required buckets on startup and takes its credentials from S3_ACCESS_KEY and S3_SECRET_KEY.
Installations that ran the earlier MinIO service start with an empty seaweedfs_data volume. Before switching, copy the uploads and processed-files buckets from MinIO with an S3 tool such as rclone sync and keep the object keys unchanged. Keep the old minio_data volume until the copy is verified.
Qdrant
Qdrant stores vector indexes for retrieval. Each embedding model has its own collection, named orcai-chunks-g<generation>-<model>-<dimensions>, whose vector size is the model's dimensions.
SpiceDB
SpiceDB backs authorisation checks. The repository includes schema files under packages/spice-db/src/schema and commands to apply or inspect the schema.
AI endpoint
OrcAI gets embeddings from the OpenAI-compatible endpoint and model an instance admin saves on the instance Settings page (see Embeddings). Chat, Assistant and utility models, including image descriptions, use the providers configured in the app.
Text extraction
Kreuzberg extracts the text of uploaded files. OCR requires Tesseract in the worker environment.