# Onyx Project Structure: A Complete Guide to the Modular AI Platform Repository

> Explore the Onyx project structure a complete guide to the modular AI platform repository. Discover how FastAPI Nextjs React Tauri and Go organize the codebase for efficient development.

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

---

**The Onyx repository organizes its codebase into seven distinct top-level directories, strictly separating FastAPI backend services, Next.js frontend applications, embeddable React widgets, Chrome extensions, Tauri desktop wrappers, and Go-based CLI tooling.**

The Onyx project structure (onyx-dot-app/onyx) implements a clean architectural boundary system that supports independent development across AI inference layers, user interface components, and deployment automation. This modular layout enables engineers to locate specific subsystems rapidly, from LLM provider integrations in the Python backend to the Vite-bundled embeddable widget consumed by third-party sites.

## Top-Level Directory Layout

The repository root contains seven functional domains plus configuration and documentation assets. Each directory maintains its own build system, dependency management, and deployment artifacts.

- **`backend/`** — Core server-side logic implementing FastAPI endpoints, Celery distributed workers, SQLAlchemy database models, and LLM provider abstractions.
  - Contains: `onyx/` (application source), `tests/` (pytest suite), `Dockerfile`, [`pyproject.toml`](https://github.com/onyx-dot-app/onyx/blob/main/pyproject.toml)
  - Entry point: [`backend/onyx/server/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/main.py)

- **`web/`** — Next.js 15+ frontend application with TypeScript and React.
  - Contains: `components/`, `pages/`, `styles/`, [`package.json`](https://github.com/onyx-dot-app/onyx/blob/main/package.json), [`next.config.js`](https://github.com/onyx-dot-app/onyx/blob/main/next.config.js), [`playwright.config.ts`](https://github.com/onyx-dot-app/onyx/blob/main/playwright.config.ts) (E2E testing)

- **`widget/`** — Standalone embeddable React component distributed as a drop-in script.
  - Contains: `src/`, [`vite.config.ts`](https://github.com/onyx-dot-app/onyx/blob/main/vite.config.ts), [`tsconfig.json`](https://github.com/onyx-dot-app/onyx/blob/main/tsconfig.json)
  - Source: [`widget/src/widget.ts`](https://github.com/onyx-dot-app/onyx/blob/main/widget/src/widget.ts)

- **`extensions/chrome/`** — Browser extension that injects the widget into arbitrary web pages.
  - Contains: [`manifest.json`](https://github.com/onyx-dot-app/onyx/blob/main/manifest.json), `public/` (icons), `src/` (content scripts)

- **`desktop/`** — Tauri-based native application wrapping the web UI for offline desktop usage.
  - Contains: `src-tauri/` (Rust source), [`tauri.conf.json`](https://github.com/onyx-dot-app/onyx/blob/main/tauri.conf.json)

- **`cli/`** — Go-based command-line interface for service orchestration and provisioning.
  - Entry point: [`cli/main.go`](https://github.com/onyx-dot-app/onyx/blob/main/cli/main.go) with `internal/` packages

- **`tools/`** — Auxiliary utilities including the `ods` (Open Source Data Sync) Go module.
  - Location: [`tools/ods/main.go`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/main.go)

- **`examples/`** — Reference implementations demonstrating widget integration and API consumption.
  - Subdirectories: `widget/`, `assistants-api/`

Additional root-level artifacts include [`AGENTS.md`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md), [`CONTRIBUTING.md`](https://github.com/onyx-dot-app/onyx/blob/main/CONTRIBUTING.md), [`docs/METRICS.md`](https://github.com/onyx-dot-app/onyx/blob/main/docs/METRICS.md), and CI/CD configurations under `.github/workflows/`.

## Backend Architecture (`backend/`)

The `backend/` directory houses the primary Python application code under `backend/onyx/`, structured around domain-driven subpackages.

### FastAPI Server Layer

The HTTP API surface resides in `backend/onyx/server/`, with [`backend/onyx/server/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/main.py) serving as the Uvicorn entry point. This layer exposes REST endpoints for chat completions, document ingestion, and administrative operations, handling authentication middleware and request validation before delegating to internal services.

### Asynchronous Task Processing

Background job execution operates through Celery workers defined in `backend/onyx/background/celery/`. The system segregates workload types across specialized queues:

- **Primary workers** — General API tasks and webhook processing
- **Docfetching workers** — External source synchronization (Google Drive, Confluence, etc.)
- **Docprocessing workers** — Text extraction, chunking, and embedding generation
- **Light/Heavy workers** — Differentiated by CPU/memory requirements for model inference

Task definitions register in `backend/onyx/background/celery/tasks/`, with the broker configuration typically targeting Redis or RabbitMQ.

### Data and Integration Layers

- **`backend/onyx/db/`** — SQLAlchemy ORM models, migration scripts, and database connection pooling utilities.
- **`backend/onyx/llm/`** — Abstractions over OpenAI, Anthropic, and local model providers, including token counting and streaming response handling.
- **`backend/onyx/tools/`** — Plugin system for external tool execution (search APIs, calculators, custom functions).
- **`backend/onyx/voice/providers/`** — Speech-to-text implementations, such as [`openai.py`](https://github.com/onyx-dot-app/onyx/blob/main/openai.py) for Whisper integration.

Observability components in `backend/onyx/tracing/` implement OpenTelemetry instrumentation for distributed tracing across the Celery and FastAPI boundaries.

## Frontend and User Interface (`web/`)

The `web/` directory contains a Next.js application utilizing the App Router architecture. TypeScript provides type safety across component boundaries, while Tailwind CSS handles styling consistency.

Key architectural decisions include:

- **API Communication** — All frontend data fetching occurs via HTTP to the FastAPI backend at `http://localhost:3000/api/...`; no direct database access occurs from the browser.
- **Component Organization** — React components segregate into feature modules (chat, search, admin settings) with shared UI primitives in `web/components/ui/`.
- **Testing Infrastructure** — Playwright configuration in [`web/playwright.config.ts`](https://github.com/onyx-dot-app/onyx/blob/main/web/playwright.config.ts) drives end-to-end validation of critical user flows.

Build artifacts from `npm run build` generate static files served by the backend or deployed to edge networks.

## Embeddable Distribution (`widget/` and `extensions/`)

Onyx distributes its conversational interface beyond the main web application through two complementary distribution mechanisms.

### Standalone Widget (`widget/`)

The `widget/` directory produces a framework-agnostic JavaScript bundle via Vite. The entry point at [`widget/src/widget.ts`](https://github.com/onyx-dot-app/onyx/blob/main/widget/src/widget.ts) initializes a React root inside a shadow DOM container, preventing CSS leakage into host sites. This artifact allows third-party websites to embed Onyx chat functionality by inserting a single `<script>` tag.

### Browser Extension (`extensions/chrome/`)

The Chrome extension under `extensions/chrome/` reuses widget components while adding browser-specific capabilities. The [`manifest.json`](https://github.com/onyx-dot-app/onyx/blob/main/manifest.json) declares content scripts that inject the widget DOM element into arbitrary pages, communicating with the Onyx backend through authenticated fetch requests. Extension-specific utilities reside in `extensions/chrome/src/`, handling tab context extraction and authentication token persistence.

## Desktop Application (`desktop/`)

The Tauri-based desktop wrapper in `desktop/` compiles the Next.js frontend into a native application. Rust code in `desktop/src-tauri/` manages window state, system tray integration, and local file system access permissions. The [`tauri.conf.json`](https://github.com/onyx-dot-app/onyx/blob/main/tauri.conf.json) defines security policies, including allowed API endpoints and CSP headers, enabling offline-first usage scenarios where the backend runs locally alongside the rendered UI.

## Developer Tooling (`cli/` and `tools/`)

### Service Management CLI (`cli/`)

Written in Go, the CLI at [`cli/main.go`](https://github.com/onyx-dot-app/onyx/blob/main/cli/main.go) provides operational commands for database migrations, configuration validation, and Kubernetes deployment generation. The `internal/` package structure separates concerns between command parsing (using Cobra or similar), API client generation, and environment configuration detection.

### Data Synchronization Tools (`tools/`)

The `tools/ods/` subdirectory contains the Open Source Data Sync utility, a Go program handling bulk export and import operations between Onyx instances and external data warehouses. This utility operates independently of the main Python backend, allowing administrative tasks to run without impacting production API latency.

## System Integration and Data Flow

The Onyx project structure enforces strict separation between presentation, business logic, and data persistence layers. The following architecture diagram illustrates communication patterns:

```text
┌─────────────┐          ┌─────────────┐
│   Frontend  │◀───────▶│   Backend   │
│ (Next.js)   │  HTTP    │ (FastAPI)   │
└─────▲───────┘          └─────▲───────┘
      │                        │
      │                        │
      │            ┌───────────┴───────────┐
      │            │   Celery Workers      │
      │            │ (async background)    │
      │            │  - docfetching          │
      │            │  - docprocessing        │
      │            │  - indexing             │
      ▼            └───────────────────────┘
┌─────────────┐
│   Widget    │ (embeddable React)
└─────▲───────┘
      │
      ▼
┌─────────────┐
│  Chrome Ext │ (injection layer)
└─────────────┘

```

**Critical integration points:**

1. **Frontend-Backend Contract** — The Next.js application consumes only the REST API exposed by `backend/onyx/server/`, ensuring the frontend remains compatible with horizontally scaled backend deployments.

2. **Asynchronous Processing** — Document ingestion and embedding generation flow through Celery queues defined in `backend/onyx/background/celery/tasks/`, preventing long-running operations from blocking HTTP request threads.

3. **Component Reuse** — The widget and Chrome extension share React component logic, maintaining feature parity across embedded and browser-extension deployment contexts.

4. **Desktop Containment** — The Tauri shell in `desktop/src-tauri/` executes the same production Next.js build served by the FastAPI backend, ensuring behavioral consistency between web and desktop deployments.

## Key Files to Explore

Understanding the Onyx project structure requires examining these representative entry points:

- **[`backend/onyx/server/main.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/main.py)** — FastAPI application factory and Uvicorn server initialization
- **[`backend/onyx/background/celery/tasks/__init__.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/background/celery/tasks/__init__.py)** — Celery task registry and queue routing definitions
- **[`web/next.config.js`](https://github.com/onyx-dot-app/onyx/blob/main/web/next.config.js)** — Next.js build configuration, rewrites, and environment variable exposure
- **[`widget/vite.config.ts`](https://github.com/onyx-dot-app/onyx/blob/main/widget/vite.config.ts)** — Vite bundling configuration for the embeddable component
- **[`extensions/chrome/manifest.json`](https://github.com/onyx-dot-app/onyx/blob/main/extensions/chrome/manifest.json)** — Extension permissions and content script declarations
- **[`desktop/src-tauri/tauri.conf.json`](https://github.com/onyx-dot-app/onyx/blob/main/desktop/src-tauri/tauri.conf.json)** — Tauri window configuration and security policies
- **[`cli/main.go`](https://github.com/onyx-dot-app/onyx/blob/main/cli/main.go)** — CLI entry point and command routing logic

## Summary

The Onyx project structure implements a polyglot, modular architecture optimized for AI platform development:

- **Seven top-level directories** isolate Python backend services, TypeScript frontend applications, and Go-based tooling
- **`backend/onyx/`** organizes FastAPI endpoints, Celery worker queues, and LLM provider integrations into domain-specific subpackages
- **`web/`** delivers the Next.js 15+ interface with Playwright-tested component libraries
- **`widget/`** and **`extensions/chrome/`** provide distribution mechanisms for third-party site integration
- **`desktop/`** wraps the web UI in a Tauri container for native offline operation
- **`cli/`** and **`tools/`** supply Go-based operational utilities for deployment and data migration

## Frequently Asked Questions

### What programming languages does the Onyx project structure use?

The repository employs **Python** for the FastAPI backend and Celery workers, **TypeScript/JavaScript** for the Next.js frontend and React widget, **Go** for the CLI and data synchronization tools, and **Rust** for the Tauri desktop application shell. This polyglot approach selects optimal languages for each subsystem's performance and ecosystem requirements.

### How does the backend handle asynchronous tasks in the Onyx project structure?

Asynchronous processing operates through **Celery** distributed task queues defined in `backend/onyx/background/celery/`. The system utilizes specialized worker types—including docfetching, docprocessing, light, and heavy queues—to isolate resource-intensive operations like document embedding generation from high-priority API request handling, ensuring responsive HTTP endpoints.

### Where is the embeddable widget code located in the Onyx repository?

The embeddable widget source resides in the **`widget/`** directory at the repository root, with the primary entry point at [`widget/src/widget.ts`](https://github.com/onyx-dot-app/onyx/blob/main/widget/src/widget.ts). The Chrome extension that injects this widget lives under **`extensions/chrome/`**, reusing the same React components while adding browser-specific manifest declarations in [`extensions/chrome/manifest.json`](https://github.com/onyx-dot-app/onyx/blob/main/extensions/chrome/manifest.json).

### What is the relationship between the web frontend and desktop application in Onyx?

The desktop application in **`desktop/`** wraps the identical Next.js build found in **`web/`** inside a Tauri container. The `desktop/src-tauri/` Rust code renders the web UI in a native window while providing system-level integrations like file system access and offline operation, ensuring feature parity between browser-based and desktop deployments without duplicating frontend code.