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

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
  • Entry point: backend/onyx/server/main.py

• web/ — Next.js 15+ frontend application with TypeScript and React.

  • Contains: components/, pages/, styles/, package.json, next.config.js, playwright.config.ts (E2E testing)

• widget/ — Standalone embeddable React component distributed as a drop-in script.

  • Contains: src/, vite.config.ts, tsconfig.json
  • Source: widget/src/widget.ts

• extensions/chrome/ — Browser extension that injects the widget into arbitrary web pages.

  • Contains: 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

• cli/ — Go-based command-line interface for service orchestration and provisioning.

  • Entry point: cli/main.go with internal/ packages

• tools/ — Auxiliary utilities including the ods (Open Source Data Sync) Go module.

  • Location: tools/ods/main.go

• examples/ — Reference implementations demonstrating widget integration and API consumption.

  • Subdirectories: widget/, assistants-api/

Additional root-level artifacts include AGENTS.md, CONTRIBUTING.md, 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 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 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 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 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 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 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 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:

┌─────────────┐          ┌─────────────┐
│   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 — FastAPI application factory and Uvicorn server initialization
• backend/onyx/background/celery/tasks/__init__.py — Celery task registry and queue routing definitions
• web/next.config.js — Next.js build configuration, rewrites, and environment variable exposure
• widget/vite.config.ts — Vite bundling configuration for the embeddable component
• extensions/chrome/manifest.json — Extension permissions and content script declarations
• desktop/src-tauri/tauri.conf.json — Tauri window configuration and security policies
• 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. 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}