Architecture
How the OrcAI app, workers, storage, authorization, retrieval, and AI services fit together.
OrcAI is split into a main app, worker process, and infrastructure services.
At A Glance
Runtime Components
- React 19 and TanStack Start power the user interface and server runtime.
- TanStack Router, Query, and Form are used for client routing and data workflows.
- oRPC defines typed backend contracts.
- Better Auth handles authentication.
- Drizzle ORM manages PostgreSQL access and migrations.
- pg-boss coordinates background jobs.
- Qdrant stores vector indexes.
- SpiceDB handles authorization relationships and permission checks.
- S3-compatible storage stores uploaded and processed files.
- Kreuzberg and Tesseract handle document extraction and OCR.
- The AI SDK talks to an OpenAI-compatible model endpoint.
Generated API reference
Each OrcAI instance serves its live, Scalar-powered API reference at
/api/doc in the main app. The OpenAPI document is generated directly from
the oRPC router, so it reflects the API exposed by that deployed version.
Content Processing Flow
- A user uploads material through the app.
- The app stores files in S3-compatible object storage.
- The app creates background jobs.
- Workers extract content from the uploaded material.
- Workers create processed artifacts and metadata.
- Workers generate embeddings using the configured model endpoint.
- Workers write vector data to Qdrant.
- Chat tools query Qdrant and retrieve relevant content for model calls.
Authorization Flow
The app stores domain records in PostgreSQL and uses SpiceDB for relationship-based authorization. Permission middleware checks whether a user can access or mutate a resource before executing protected operations.
TODO
Document the concrete resource types, relations, and permissions from the SpiceDB schema.
AI Flow
Chat generation uses configured providers and models. Retrieval tools can search knowledge-base content, list documents, and fetch pages or chunks before the assistant response is generated.
Image-related processing can use GENERAL_MODEL to describe images during asset processing.
TODO
Document provider/model configuration from the admin UI once the expected operator workflow is confirmed.
Observability
The repository includes optional Umami analytics and OpenTelemetry export configuration.
TODO
Document recommended dashboards, spans, metrics, and log fields.