# openchatui/openchat architecture

> Architecture diagram of the GitHub repository openchatui/openchat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openchatui/openchat
- Repository: https://github.com/openchatui/openchat

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a strong separation between **UI pages**, **API routes**, **domain services**, and **database access**.
   - The product is an **AI workspace** rather than a single chat UI: chat, models, drive/docs, audio, video, web search, code execution, users/groups, and admin configuration all live in the same runtime.

2. **Frontend presentation layer**
   - Routes under `app/(auth)` and `app/(main)` define the visible app surfaces: login/signup, the main chat area, archive, search, settings, drive, and the admin console.
   - Most screens are composed from `components/*`, with large feature folders such as `components/chat`, `components/drive`, `components/admin`, `components/search`, and `components/docs`.
   - This layer is primarily presentational and interactive; it does not own business logic.

3. **Client-side data access**
   - Feature hooks in `hooks/*` are the main bridge from UI to backend, e.g. chat streaming, drive file lists, pinned models, users, tags, connections, audio, and admin settings.
   - Those hooks call small API client wrappers in `lib/api/*`, which centralize HTTP requests and response typing.
   - In architecture terms, the browser talks to the app through these hooks, not directly to domain services.

4. **Backend API boundary**
   - The primary backend surface is `app/api/v1/*`, organized by domain: chats, models, users, groups, drive, audio, video, websearch, code, connections, and activity.
   - There is also `app/api/auth/[...nextauth]` for session-based authentication, plus `app/api/docs/*` for Swagger/OpenAPI docs.
   - These route handlers are the API entry points that connect external clients, the frontend, and the domain layer.

5. **Domain/service layer**
   - Core behavior lives in `lib/modules/*`, which is split by capability:
     - `chat` for chat orchestration and client/store logic
     - `ai` and `tools` for provider/tool abstractions
     - `drive` for document/file sync and storage abstraction
     - `search` for search orchestration
     - `audio`, `web-browsing`, `image-generation`, `video-generation`, and `pyodide` for specialized AI features
     - `access-control` for permissions and model access rules
   - This layer is where the app’s feature logic is concentrated, and it sits between API handlers and persistence/providers.

6. **Persistence layer**
   - Database access is isolated in `lib/db/*`, with separate modules for chats, users, groups, models, api keys, configs, connections, drive, images, video, websearch, and code.
   - Prisma is the ORM, with separate schemas for **SQLite** and **PostgreSQL** under `prisma/`, plus a long migration history that reflects the product’s growing feature set.
   - The repo is clearly designed to support both local self-hosted SQLite and production PostgreSQL.

7. **Authentication, authorization, and identity**
   - Authentication is session-based through NextAuth-style routes and services under `lib/auth/*`.
   - Authorization is not just “logged in / logged out”: there are roles, groups, permissions, API keys, and per-model access controls.
   - The admin area and several API endpoints are protected by middleware and authz services, making identity a first-class architectural boundary.

8. **AI provider and tool integration**
   - The app is provider-agnostic at the core: `lib/modules/ai/providers` and `lib/modules/tools/*` adapt to external AI services.
   - Material external integrations include **OpenAI**, **Ollama**, **Google Drive**, **Deepgram**, **ElevenLabs**, **Browserless/Browserbase-style web browsing**, and **Google PSE**.
   - These integrations are exposed through feature-specific APIs and admin configuration screens, so provider wiring is a runtime concern rather than hardcoded application logic.

9. **Chat subsystem**
   - Chat is a major domain with dedicated pages, components, hooks, and server APIs.
   - The flow is: user input in chat UI → streaming/chat hooks → `/api/v1/chat*` and `/api/v1/chats*` endpoints → chat service and persistence.
   - Features around chat include attachments, titles, archives, model selection, prompt suggestions, live activity, and message history.

10. **Drive and documents subsystem**
   - Drive is its own product area with folder/file browsing, upload/download, preview, star/trash/restore, search, and sync.
   - The backend separates **file/folder operations** from **provider sync/configuration**, allowing either Google Drive or local document storage behavior.
   - The UI includes rich file previews for PDFs, Office docs, images, videos, CSVs, and folder navigation, so the architecture treats files as first-class managed content.

11. **Admin and configuration surfaces**
   - `app/(main)/admin` and `components/admin/*` form a centralized control plane for models, connections, users, groups, UI settings, audio, image, video, code interpreter, web search, and drive.
   - Many admin screens correspond directly to config endpoints under `app/api/v1/*/config` and `*/config/update`.
   - This suggests a “configure everything from inside the app” architecture, where runtime behavior is controlled through persisted settings.

12. **Supporting features and auxiliary systems**
   - There are dedicated surfaces for **search**, **archive**, **settings**, **activity tracking** (`heartbeat`, active users), **public files/images/profiles** routes, and **setup/bootstrap**.
   - Swagger docs are built into the app, which makes the REST API a deliberate part of the product surface, not just an internal implementation detail.
   - A separate `scripts/` area includes tooling for browser automation tests and collaborative editing support, indicating some features rely on additional runtime processes beyond the main Next.js server.

13. **Key architectural diagram takeaway**
   - A useful diagram should show:
     - Browser/UI layers on the left
     - Next.js pages and route handlers in the middle
     - Domain services/modules and DB access below
     - External AI/content providers on the right
     - Prisma-backed SQLite/PostgreSQL persistence at the bottom
   - The main data flow is **UI → hooks/API client → REST route → service/module → DB or external provider → response back to UI**.

Main entry points: [`app/api/v1/chat/route.ts`](https://github.com/openchatui/openchat/blob/main/app/api/v1/chat/route.ts) (V1 API), [`app/(main)/layout.tsx`](https://github.com/openchatui/openchat/blob/main/app/(main)/layout.tsx) (Main app), [`lib/api/http.ts`](https://github.com/openchatui/openchat/blob/main/lib/api/http.ts) (API clients), [`lib/db/chats.db.ts`](https://github.com/openchatui/openchat/blob/main/lib/db/chats.db.ts) (DB modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_main["Main app<br/>Next.js shell<br/>[layout.tsx]"]
  node_app_auth["Auth pages<br/>Next.js routes<br/>[page.tsx]"]
  node_chat_ui["Chat UI<br/>Feature pages<br/>[page.tsx]"]
  node_drive_ui["Drive UI<br/>Feature pages<br/>[page.tsx]"]
  node_admin_ui["Admin UI<br/>Feature pages<br/>[page.tsx]"]
  node_settings_ui["Settings<br/>Feature pages<br/>[page.tsx]"]
  node_feature_components["Feature components<br/>UI library<br/>[chat-standard.tsx]"]
  node_feature_hooks["Client hooks<br/>State/data hooks"]
  node_api_clients["API clients<br/>HTTP wrappers<br/>[http.ts]"]
end

subgraph group_backend["Backend API"]
  node_api_auth["Auth API<br/>Route handler<br/>[route.ts]"]
  node_api_v1["V1 API<br/>REST routes<br/>[route.ts]"]
  node_api_docs["API docs<br/>Swagger docs<br/>[route.ts]"]
end

subgraph group_domain["Domain Services"]
  node_authz["Auth & access<br/>Security layer<br/>[authz.ts]"]
  node_chat_service["Chat service<br/>Conversation orchestration<br/>[chat.service.ts]"]
  node_drive_service["Drive service<br/>File orchestration<br/>[service.ts]"]
  node_search_tools["Search/tools<br/>AI tools<br/>[search.service.ts]"]
end

subgraph group_data["Persistence"]
  node_db_modules[("DB modules<br/>Data access<br/>[chats.db.ts]")]
  node_prisma_schemas["Prisma schemas<br/>ORM schema"]
end

subgraph group_integrations["Integrations"]
  node_ai_providers["AI providers<br/>Provider adapters"]
  node_external_integrations["External services<br/>Third-party APIs"]
end

node_app_main -->|"renders"| node_chat_ui
node_app_main -->|"renders"| node_drive_ui
node_app_main -->|"renders"| node_admin_ui
node_app_main -->|"renders"| node_settings_ui
node_app_auth -->|"authenticates"| node_authz
node_feature_components -->|"builds"| node_chat_ui
node_feature_components -->|"builds"| node_drive_ui
node_feature_components -->|"builds"| node_admin_ui
node_feature_hooks -->|"calls"| node_api_clients
node_api_clients -->|"requests"| node_api_v1
node_api_clients -->|"requests"| node_api_auth
node_api_v1 -->|"guards"| node_authz
node_api_v1 -->|"orchestrates"| node_chat_service
node_api_v1 -->|"orchestrates"| node_drive_service
node_api_v1 -->|"orchestrates"| node_search_tools
node_api_v1 -->|"adapts"| node_ai_providers
node_api_v1 -->|"persists"| node_db_modules
node_chat_service -->|"stores"| node_db_modules
node_drive_service -->|"stores"| node_db_modules
node_search_tools -->|"uses"| node_external_integrations
node_ai_providers -->|"connects"| node_external_integrations
node_db_modules -->|"maps to"| node_prisma_schemas
node_api_docs -->|"documents"| node_api_v1
node_settings_ui -->|"configures"| node_api_clients

click node_app_main "https://github.com/openchatui/openchat/blob/main/app/(main)/layout.tsx"
click node_app_auth "https://github.com/openchatui/openchat/blob/main/app/(auth)/login/page.tsx"
click node_chat_ui "https://github.com/openchatui/openchat/blob/main/app/(main)/c/[id]/page.tsx"
click node_drive_ui "https://github.com/openchatui/openchat/blob/main/app/(main)/drive/page.tsx"
click node_admin_ui "https://github.com/openchatui/openchat/blob/main/app/(main)/admin/page.tsx"
click node_settings_ui "https://github.com/openchatui/openchat/blob/main/app/(main)/settings/page.tsx"
click node_feature_components "https://github.com/openchatui/openchat/blob/main/components/chat/chat-standard.tsx"
click node_feature_hooks "https://github.com/openchatui/openchat/blob/main/hooks/useChatStreaming.ts"
click node_api_clients "https://github.com/openchatui/openchat/blob/main/lib/api/http.ts"
click node_api_auth "https://github.com/openchatui/openchat/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_api_v1 "https://github.com/openchatui/openchat/blob/main/app/api/v1/chat/route.ts"
click node_api_docs "https://github.com/openchatui/openchat/blob/main/app/api/docs/route.ts"
click node_authz "https://github.com/openchatui/openchat/blob/main/lib/auth/authz.ts"
click node_chat_service "https://github.com/openchatui/openchat/blob/main/lib/modules/chat/chat.service.ts"
click node_drive_service "https://github.com/openchatui/openchat/blob/main/lib/modules/drive/service.ts"
click node_search_tools "https://github.com/openchatui/openchat/blob/main/lib/modules/search/search.service.ts"
click node_ai_providers "https://github.com/openchatui/openchat/blob/main/lib/modules/ai/providers/provider.service.ts"
click node_external_integrations "https://github.com/openchatui/openchat/blob/main/lib/modules/drive/providers/google-drive.service.ts"
click node_db_modules "https://github.com/openchatui/openchat/blob/main/lib/db/chats.db.ts"
click node_prisma_schemas "https://github.com/openchatui/openchat/blob/main/prisma/schema.postgres.prisma"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_main,node_app_auth,node_chat_ui,node_drive_ui,node_admin_ui,node_settings_ui,node_feature_components,node_feature_hooks,node_api_clients toneBlue
class node_api_auth,node_api_v1,node_api_docs toneAmber
class node_authz,node_chat_service,node_drive_service,node_search_tools toneMint
class node_db_modules,node_prisma_schemas toneRose
class node_ai_providers,node_external_integrations toneIndigo
```

## Components

### Frontend

App Router pages, UI shells, and feature components.

- [Main app](https://github.com/openchatui/openchat/blob/main/app/(main)/layout.tsx): Next.js shell · Authenticated app runtime and main workspace routes. · `app/(main)/layout.tsx`
- [Auth pages](https://github.com/openchatui/openchat/blob/main/app/(auth)/login/page.tsx): Next.js routes · Login and signup surfaces. · `app/(auth)/login/page.tsx`
- [Chat UI](https://github.com/openchatui/openchat/blob/main/app/(main)/c/[id]/page.tsx): Feature pages · Primary conversation surfaces and chat interactions. · `app/(main)/c/[id]/page.tsx`
- [Drive UI](https://github.com/openchatui/openchat/blob/main/app/(main)/drive/page.tsx): Feature pages · Drive browsing, preview, and file management screens. · `app/(main)/drive/page.tsx`
- [Admin UI](https://github.com/openchatui/openchat/blob/main/app/(main)/admin/page.tsx): Feature pages · Centralized configuration and management console. · `app/(main)/admin/page.tsx`
- [Settings](https://github.com/openchatui/openchat/blob/main/app/(main)/settings/page.tsx): Feature pages · Profile, keys, and integration settings screens. · `app/(main)/settings/page.tsx`
- [Feature components](https://github.com/openchatui/openchat/blob/main/components/chat/chat-standard.tsx): UI library · Chat, drive, search, docs, and admin components reused across screens. · `components/chat/chat-standard.tsx`
- [Client hooks](https://github.com/openchatui/openchat/blob/main/hooks/useChatStreaming.ts): State/data hooks · Browser-side bridge for streaming, lists, settings, and mutations. · `hooks/useChatStreaming.ts`
- [API clients](https://github.com/openchatui/openchat/blob/main/lib/api/http.ts): HTTP wrappers · Typed request helpers for app API routes. · `lib/api/http.ts`

### Backend API

Route handlers and API boundary for the Next.js runtime.

- [Auth API](https://github.com/openchatui/openchat/blob/main/app/api/auth/[...nextauth]/route.ts): Route handler · Session and authentication entry point. · `app/api/auth/[...nextauth]/route.ts`
- [V1 API](https://github.com/openchatui/openchat/blob/main/app/api/v1/chat/route.ts): REST routes · Primary domain API surface for the app. · `app/api/v1/chat/route.ts`
- [API docs](https://github.com/openchatui/openchat/blob/main/app/api/docs/route.ts): Swagger docs · OpenAPI and Swagger documentation routes. · `app/api/docs/route.ts`

### Domain Services

Core orchestration, auth, and feature logic.

- [Auth & access](https://github.com/openchatui/openchat/blob/main/lib/auth/authz.ts): Security layer · Auth service, API keys, roles, and permissions. · `lib/auth/authz.ts`
- [Chat service](https://github.com/openchatui/openchat/blob/main/lib/modules/chat/chat.service.ts): Conversation orchestration · Chat flow, client store, and message handling. · `lib/modules/chat/chat.service.ts`
- [Drive service](https://github.com/openchatui/openchat/blob/main/lib/modules/drive/service.ts): File orchestration · Drive operations, storage abstraction, and sync behavior. · `lib/modules/drive/service.ts`
- [Search/tools](https://github.com/openchatui/openchat/blob/main/lib/modules/search/search.service.ts): AI tools · Search orchestration plus web, code, image, and video tools. · `lib/modules/search/search.service.ts`

### Persistence

Prisma schemas and database access modules.

- [DB modules](https://github.com/openchatui/openchat/blob/main/lib/db/chats.db.ts): Data access · Repository-style database access for chats, users, groups, models, drive, and config. · `lib/db/chats.db.ts`
- [Prisma schemas](https://github.com/openchatui/openchat/blob/main/prisma/schema.postgres.prisma): ORM schema · SQLite and PostgreSQL schema definitions. · `prisma/schema.postgres.prisma`

### Integrations

External providers and runtime adapters.

- [AI providers](https://github.com/openchatui/openchat/blob/main/lib/modules/ai/providers/provider.service.ts): Provider adapters · Provider-agnostic integration layer for external AI services. · `lib/modules/ai/providers/provider.service.ts`
- [External services](https://github.com/openchatui/openchat/blob/main/lib/modules/drive/providers/google-drive.service.ts): Third-party APIs · OpenAI, Ollama, Google Drive, Deepgram, ElevenLabs, and browsing/search providers. · `lib/modules/drive/providers/google-drive.service.ts`

## Connections

- Main app → Chat UI: renders · Main workspace hosts chat, archive, search, settings, drive, and admin surfaces.
- Main app → Drive UI: renders · Drive routes live inside the authenticated app shell.
- Main app → Admin UI: renders · Admin console is part of the same app runtime.
- Main app → Settings: renders · Settings pages are mounted under the main shell.
- Auth pages → Auth & access: authenticates · Login and signup feed session-based authentication.
- Feature components → Chat UI: builds · Chat screens are assembled from shared feature components.
- Feature components → Drive UI: builds · Drive views rely on specialized preview and file-management components.
- Feature components → Admin UI: builds · Admin screens are composed from feature-specific components.
- Client hooks → API clients: calls · Hooks use typed API wrappers for browser-server communication.
- API clients → V1 API: requests · Client wrappers target the REST API routes.
- API clients → Auth API: requests · Client auth flows use the NextAuth route.
- V1 API → Auth & access: guards · API handlers enforce roles, keys, permissions, and access rules.
- V1 API → Chat service: orchestrates · Chat endpoints delegate conversation behavior to the chat domain.
- V1 API → Drive service: orchestrates · Drive endpoints delegate file and sync operations to the drive domain.
- V1 API → Search/tools: orchestrates · Search, code, audio, video, and browsing routes use shared tool services.
- V1 API → AI providers: adapts · Domain services resolve external model/provider integrations through adapters.
- V1 API → DB modules: persists · API handlers read and write through data-access modules.
- Chat service → DB modules: stores · Chats, messages, titles, and archives are persisted in the database layer.
- Drive service → DB modules: stores · Drive metadata and content state are persisted through dedicated DB modules.
- Search/tools → External services: uses · Search and tool execution depend on external browsing and AI services.
- AI providers → External services: connects · Provider adapters bridge to OpenAI, Ollama, and other services.
- DB modules → Prisma schemas: maps to · Database modules are implemented on top of Prisma schemas and migrations.
- API docs → V1 API: documents · Swagger/OpenAPI describes the REST surface.
- Settings → API clients: configures · Settings screens update integrations, keys, and profile data via API clients.