# openchatai/openchat architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, multi-service chatbot console (“OpenChat”) that orchestrates several backends and frontends to let users spin up custom LLM-powered chatbots.
- The README states that the original Laravel backend (“backend-server”) has been largely rewritten in Python/Django (“dj_backend_server”), with an auxiliary Next.js/TypeScript “llm-server” for embedding and chat operations, plus a React-based widget under `widgets/search`.

##### File structure
- Top-level services:
- backend-server – legacy Laravel PHP REST/Web controllers & Blade views
- dj_backend_server – new Django REST + WebSocket (Channels) app, Celery tasks, admin, templates, static assets
- llm-server – Next.js API routes for chat/ingest, vector-DB logic in TS
- widgets/search – standalone React widget packaged via Vite
- Deployment configs: `docker-compose.yml`, service Dockerfiles, Makefiles
- Data/config: environment files (`common.env`, `example.env`), vector-DB config under `llm-server/config`
- Infra: nginx templates, Celery broker/worker, Django Channels routing

##### Key insights from the README
- Uses OpenAI (or Azure) for LLM calls
- Supports Pinecone or Qdrant vector databases
- Python Django is primary backend, with Celery for background ingestion
- Frontend will be migrated to Next.js/TS; for now, Django templates & the React widget co-exist

- Client UIs
– Browser clients hitting Django templates
– Embedded React widget (`widgets/search`) on customer sites
- Django Backend (`dj_backend_server`)
– Django REST API endpoints
– WebSocket consumers (Channels)
– Celery Workers for ingestion tasks
- LLM Microservice (`llm-server`)
– Next.js API routes (`/api/ingest`, `/api/chat`)
– Embedding & retrieval logic
- Data Stores
– Relational DB (Postgres/MySQL for Django models)
– Message broker (Redis/RabbitMQ for Celery)
– Vector store (Pinecone or Qdrant)
- External LLM APIs
– OpenAI (or Azure OpenAI)

1. User → Django REST or WebSocket
2. Django API → Celery (enqueue ingest/chat tasks)
3. Celery Worker → llm-server ingest endpoint (send documents or codebase)
4. llm-server → Vector Store (upsert embeddings)
5. User → Django API chat endpoint → llm-server chat endpoint →
Vector Store + OpenAI → llm-server response → Django → Client
6. Django ↔ Relational DB for user/chatbot metadata & chat histories

c. Architectural patterns & principles
- Microservice separation of concerns: Django for orchestration, Next.js for vector/LLM logic
- Event-driven ingestion via Celery tasks and listeners
- CQRS-like read/write separation (writes via ingestion pipeline, reads via vector retrieval)
- WebSocket pub/sub for real-time chat (Django Channels)

d. Key technologies & frameworks
- Python/Django, Django REST Framework, Django Channels, Celery
- Node.js/Next.js, TypeScript
- Pinecone or Qdrant vector DB
- Redis or RabbitMQ
- OpenAI/Azure OpenAI APIs
- Docker, Docker Compose, nginx

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client UIs
    subgraph "Client UIs"
        direction TB
        Browser["Browser Client"]:::ui
        Widget["Embedded React Widget"]:::ui
    end

    %% Django Orchestration Backend
    subgraph "Django Orchestration Backend"
        direction TB
        DjangoTemplates["Django Templates & Static"]:::ui
        DjangoAPI["Django REST API"]:::django
        WebSocket["WebSocket Consumers"]:::django
        CeleryWorker["Celery Worker"]:::django
    end

    %% LLM Microservice
    subgraph "LLM Microservice"
        direction TB
        ChatAPI["Next.js Chat Endpoint"]:::micro
        IngestAPI["Next.js Ingest Endpoint"]:::micro
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RelationalDB["Relational DB<br/>(Postgres/MySQL)"]:::datastore
        MessageBroker["Message Broker<br/>(Redis/RabbitMQ)"]:::datastore
        VectorStore["Vector Store<br/>(Pinecone/Qdrant)"]:::datastore
    end

    %% External LLM
    subgraph "External LLM APIs"
        OpenAI["OpenAI/Azure OpenAI"]:::external
    end

    %% Connections
    Browser -->|“HTTP Request”| DjangoAPI
    Browser -->|“Load Pages”| DjangoTemplates
    Widget -->|“Embed Chat”| DjangoAPI

    DjangoAPI -->|“enqueue ingest task”| MessageBroker
    MessageBroker -->|“consume task”| CeleryWorker
    CeleryWorker -->|“POST /api/ingest”| IngestAPI
    IngestAPI -->|“upsert embeddings”| VectorStore

    DjangoAPI -->|“chat request”| ChatAPI
    ChatAPI -->|“query embeddings”| VectorStore
    ChatAPI -->|“LLM call”| OpenAI
    ChatAPI -->|“response”| DjangoAPI

    DjangoAPI -->|“CRUD metadata”| RelationalDB
    WebSocket -->|“WS connect/chat”| Browser

    %% Click Events
    click DjangoAPI "https://github.com/openchatai/openchat/tree/main/dj_backend_server/api/views/"
    click WebSocket "https://github.com/openchatai/openchat/blob/main/dj_backend_server/channels/consumers.py"
    click CeleryWorker "https://github.com/openchatai/openchat/blob/main/dj_backend_server/api/tasks.py"
    click ChatAPI "https://github.com/openchatai/openchat/blob/main/llm-server/pages/api/chat.ts"
    click IngestAPI "https://github.com/openchatai/openchat/blob/main/llm-server/pages/api/ingest.ts"
    click Widget "https://github.com/openchatai/openchat/blob/main/widgets/search/src/App.tsx"
    click MessageBroker "https://github.com/openchatai/openchat/blob/main/docker-compose.yml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#004085,color:#004085;
    classDef django fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef micro fill:#E6D5FF,stroke:#5E35B1,color:#5E35B1;
    classDef datastore fill:#FFE0B2,stroke:#EF6C00,color:#EF6C00;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333;
```
