# What Is Onyx Dot App Onyx? Open-Source AI Platform Architecture Explained

> Discover Onyx dot app Onyx an open-source AI platform offering enterprise search RAG and conversational AI. Learn about its FastAPI Next.js and Celery architecture.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: architecture
- Published: 2026-03-28

---

**Onyx dot app Onyx is an open-source, self-hostable AI platform that delivers enterprise search, RAG (Retrieval-Augmented Generation), and conversational AI through a FastAPI backend, Next.js frontend, and distributed Celery worker architecture.**

The `onyx-dot-app/onyx` repository on GitHub provides a complete infrastructure stack for organizations requiring secure, self-hosted alternatives to managed AI services. This platform combines modern web frameworks with vector databases and large language models to index, search, and chat with internal knowledge bases.

## Core Architecture and Technology Stack

Onyx dot app Onyx is built on a layered architecture that separates real-time API handling from heavy background processing.

### API Server and Backend

The **FastAPI** server serves as the central nervous system, exposing REST endpoints for chat, search, document management, and authentication. In [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py), the application factory builds the FastAPI instance, registers all routers using `include_router_with_global_prefix_prepended`, and configures automatic OpenAPI operation IDs via `use_route_function_names_as_operation_ids`. The server runs on Python 3.11 and initializes telemetry through Sentry and OpenTelemetry as defined in [`backend/onyx/tracing/setup.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/tracing/setup.py).

### Frontend Interface

The user interface is implemented in **Next.js 15** with **React 18** and **TypeScript**, located in the `/web/` directory. This provides the interactive Chat UI, admin dashboards, and document upload workflows. The frontend communicates with the backend via prefixed API routes (controlled by `APP_API_PREFIX`).

### Background Processing

**Celery** workers handle asynchronous tasks including connector fetching, document chunking, embedding generation, and knowledge-graph clustering. These workers are organized into taxonomy groups such as **Docfetching** and **Docprocessing**, defined in the `backend/onyx/background/tasks/` directory.

### Data Persistence

- **Vector Store**: **Vespa** stores dense embeddings for similarity search, with an optional PostgreSQL cache layer configurable via `CACHE_BACKEND=postgres`
- **Metadata Database**: **PostgreSQL** persists user accounts, access controls, and document metadata through the SQL engine at [`backend/onyx/db/engine/sql_engine.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/db/engine/sql_engine.py)
- **Cache Layer**: **Redis** (default) or PostgreSQL handles transient data and job queues

### Authentication and Security

The platform supports **OAuth2**, **OIDC**, **SAML**, and basic authentication through the user management system in [`backend/onyx/auth/users.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/auth/users.py). Every route undergoes authorization validation via [`backend/onyx/server/auth_check.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/auth_check.py).

## Request Flow and Data Processing

Understanding the data flow helps clarify how Onyx dot app Onyx handles queries:

1. **Client Request**: The browser loads the Next.js UI, which streams user input to the backend
2. **API Validation**: FastAPI validates requests at endpoints like `/api/chat` (defined in [`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py)) and checks authentication metadata
3. **Direct Response or Enqueue**: For simple queries, the API returns data immediately; for document processing, it enqueues Celery tasks
4. **Background Execution**: Celery workers fetch documents from connectors, chunk content, generate embeddings via the model server, and write vectors to Vespa
5. **Result Persistence**: Processed data lands in PostgreSQL or Vespa, becoming available for subsequent RAG queries

The middleware layer in [`backend/onyx/utils/middleware.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/utils/middleware.py) injects request IDs and endpoint context throughout this pipeline for tracing.

## Configuration and Deployment Modes

Onyx dot app Onyx supports flexible deployment scenarios through environment variables:

- **Multi-tenancy**: Set `MULTI_TENANT=true` for isolated tenant environments (requires vector DB); use `DISABLE_VECTOR_DB=true` for lean single-tenant deployments
- **Cache Backend**: Choose between Redis (`CACHE_BACKEND=redis`) or PostgreSQL-based caching
- **LLM Providers**: Configure OpenAI, Anthropic, Gemini, Ollama, or vLLM through the LiteLLM integration

## Running Onyx Locally

### Starting the Backend Server

```bash

# Activate Python environment

source .venv/bin/activate

# Configure environment for local development

export APP_HOST=0.0.0.0
export APP_PORT=8000
export POSTGRES_WEB_APP_NAME=onyx
export OAUTH_ENABLED=false
export DISABLE_VECTOR_DB=true

# Launch FastAPI server (auto-detects EE vs CE)

python -m backend.onyx.main

```

The entry point at [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) (lines 84-92) launches `uvicorn` and initializes the complete application stack.

### Testing the Chat API

```bash
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Explain Onyx architecture"}]}'

```

This request hits the `chat_router` and streams LLM responses back to the client.

### Triggering Document Indexing

```bash
curl -X POST http://localhost:8000/api/connector/sync \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"connector_id":"12345"}'

```

This enqueues a **Docfetching** Celery worker to pull documents and spawn **Docprocessing** tasks for indexing.

### Extending with Custom Routes

Create [`backend/onyx/server/custom/example.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/custom/example.py):

```python
from fastapi import APIRouter

router = APIRouter()

@router.get("/hello")
def hello() -> dict:
    return {"msg": "Hello from Onyx custom route!"}

```

Register in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py):

```python
from onyx.server.custom.example import router as example_router
include_router_with_global_prefix_prepended(application, example_router)

```

All custom routes automatically receive the global `/api` prefix.

## Essential Source Files

| File | Purpose |
|------|---------|
| [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) | FastAPI application factory, router registration, middleware setup |
| [`backend/onyx/db/engine/sql_engine.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/db/engine/sql_engine.py) | PostgreSQL connection management and session handling |
| [`backend/onyx/auth/users.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/auth/users.py) | OAuth2, OIDC, and SAML authentication implementations |
| [`backend/onyx/server/query_and_chat/chat_backend.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/query_and_chat/chat_backend.py) | Chat endpoint definitions and streaming logic |
| `backend/onyx/background/tasks/` | Celery task definitions for document processing |
| [`backend/onyx/tracing/setup.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/tracing/setup.py) | Sentry and OpenTelemetry initialization |
| [`web/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/web/README.md) | Frontend setup and component architecture documentation |
| [`AGENTS.md`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md) | Contributor knowledge base covering worker taxonomy and testing |

## Summary

- **Onyx dot app Onyx** provides a complete open-source stack for enterprise AI search and chat, combining FastAPI, Next.js, and Celery
- The architecture separates real-time API handling from background document processing using PostgreSQL, Vespa, and Redis
- Deployment flexibility supports both multi-tenant production environments and lightweight single-tenant setups via `DISABLE_VECTOR_DB`
- Authentication integrates with existing enterprise systems through OAuth2, OIDC, and SAML protocols
- Extension points in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) allow custom router registration while maintaining automatic API prefixing and OpenAPI documentation

## Frequently Asked Questions

### What is Onyx dot app Onyx used for?

Onyx dot app Onyx serves as an internal knowledge management platform that enables employees to search across scattered documents and data sources using natural language. It powers AI chatbots that reference actual company documents through RAG technology, ensuring answers are grounded in private data rather than generic training data.

### Is Onyx dot app Onyx free for commercial use?

Yes, Onyx dot app Onyx is fully open-source under the MIT license and free for both personal and commercial self-hosted deployments. The repository at `onyx-dot-app/onyx` contains the complete source code for the backend, frontend, and worker processes without feature restrictions.

### What infrastructure is required to run Onyx dot app Onyx?

The platform requires **PostgreSQL** for metadata storage, optional **Vespa** for vector search (can be disabled with `DISABLE_VECTOR_DB=true`), and **Redis** for caching and job queues (or PostgreSQL as an alternative cache). The backend runs on Python 3.11, while the frontend requires Node.js for the Next.js build process.

### How can I customize the API behavior in Onyx dot app Onyx?

Developers can add custom functionality by creating new FastAPI routers in the `backend/onyx/server/custom/` directory and registering them in [`backend/onyx/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/main.py) using `include_router_with_global_prefix_prepended`. This approach automatically applies the global API prefix and maintains consistent OpenAPI documentation standards across the application.