# n4ze3m/dialoqbase architecture

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

- Interactive diagram: https://gitdiagram.com/n4ze3m/dialoqbase
- Repository: https://github.com/n4ze3m/dialoqbase

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source chatbot platform (Dialoqbase) delivered as a monorepo.
- It includes:
- A Fastify-based Node.js backend (“server/”).
- A React/Vite-powered admin UI (“app/ui/”).
- A standalone embeddable chat widget (“app/widget/”).
- A script bundle for web-embed (“app/script/”).
- The system leverages PostgreSQL (vector search), Redis (caching/queues), a job queue (Bull), and pluggable AI providers (OpenAI, Anthropic, etc.).

##### Directory Structure Indicators
- Top-level “server/”: Fastify app, Prisma ORM, Cron jobs, queue controllers, integration handlers, embedding utilities.
- “app/ui/”: React + Ant Design admin console, page/routes, API services, state management.
- “app/widget/”: React widget, hooks, utils, communicates with backend via REST/SSE.
- “app/script/”: Rspack config to produce a single “<script>” embed for external sites.
- “docker/”: Compose file spinning up server, Postgres, Redis, SearxNG.
- “docs/”: VitePress documentation of features, guides, reference.

##### Key Architecture Patterns
- Monorepo + pnpm workspace for shared types & consistent versioning.
- Separation of concerns: Admin UI vs. Public widget vs. Backend API vs. Embedding script.
- API versioning under “/api/v1/…” routes and handlers.
- Event-driven processing: job queue (Bull) for document loaders & media controllers.
- Plugin architecture: Fastify plugins for JWT, Prisma, integration adapters.
- SSE for real-time chat stream (via @waylaidwanderer/fastify-sse-v2).

##### Main Components
A. Frontend “Admin UI” (app/ui)
- React SPA served by the backend or a static host.
- Routes → API calls to server’s /api/v1 endpoints.
B. Embeddable Widget (app/widget & app/script)
- JavaScript bundle installed on external sites.
- Communicates with backend via REST + SSE.
C. Backend API (server/src/app.ts)
- Fastify HTTP server exposing REST/SSE endpoints under /api/v1.
- Handlers for bots, conversations, playground, admin, integrations.
D. Data Stores
- PostgreSQL (vector DB for embeddings + relational data).
- Redis (caching & Bull job queue).
E. Job Queue & Workers (server/src/queue)
- Controllers for parsing/loading docs, crawlers, media → enqueue jobs → process embeddings.
F. External Services & Integrations
- AI Providers (OpenAI, Anthropic, Fireworks, Google, etc.).
- Message & voice integrations (Telegram, Discord, WhatsApp).
- SearxNG search (optional via docker).

##### Relationships and Data Flows
- Admin UI ←(HTTPS/REST)→ Backend API → (Prisma) → PostgreSQL
- Widget Embed ←(HTTPS/REST+SSE)→ Backend API
- Backend → Redis (cache, locks, job queue)
- Job Workers ← Redis ← Cron / API triggers
- Job Workers → AI Providers (HTTP) → Embeddings & Chat responses
- Integration adapters listen for Telegram/Discord events → Backend handlers
- Docker Compose orchestrates Backend, Postgres, Redis, SearxNG

##### Architectural Design Principles
- Clear API boundaries (versioned routes under /api/v1).
- Modular Fastify plugins (jwt, prisma, integration).
- Shared type definitions for contract consistency (app/ui/@types vs. server/schema).
- Asynchronous processing for heavy tasks via Bull.
- Embeddability and extensibility (script packaging with Rspack).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Layer
    subgraph "Monorepo"
        subgraph "Admin UI"
            AdminUI["Admin UI<br/>(React/Vite)"]:::frontend
        end
        subgraph "Widget"
            Widget["Chat Widget<br/>(React)"]:::widget
        end
        subgraph "Script"
            Script["Embed Script<br/>(Rspack)"]:::widget
        end
        subgraph "Server"
            API["Fastify API<br/>(server/src/app.ts)"]:::backend
            ApiRoutes["API Routes<br/>(server/src/routes/api/v1)"]:::backend
            ApiHandlers["API Handlers<br/>(server/src/handlers/api/v1)"]:::backend
            Plugins["Fastify Plugins<br/>(server/src/plugins)"]:::backend
            Integrations["Integration Adapters<br/>(server/src/integration)"]:::backend
            EmbUtils["Embedding Utils<br/>(transformer-embedding.ts)"]:::backend
            Loaders["Doc & Media Loaders<br/>(server/src/loader)"]:::backend
            QueueCtrls["Job Queue Controllers<br/>(server/src/queue)"]:::worker
            Cron["Cron Jobs<br/>(server/src/cron/index.ts)"]:::worker
            Prisma["Prisma ORM & Schema<br/>(server/prisma)"]:::database
            RedisUtils["Redis Utilities<br/>(redis.ts)"]:::database
            Utils["Utility Functions<br/>(server/src/utils)"]:::backend
        end
    end

    %% Datastores
    subgraph "Datastores"
        Postgres["PostgreSQL"]:::database
        Redis["Redis"]:::database
    end

    %% External Systems
    subgraph "External Systems"
        AI["AI Providers"]:::external
        Search["SearxNG"]:::external
        Events["Chat Platform Events"]:::external
    end

    %% Connections
    AdminUI -->|"REST/SSE"| API
    Widget -->|"REST/SSE"| API
    Script -->|"Loads Widget"| Widget

    API -->|"routes"| ApiRoutes
    ApiRoutes -->|"handlers"| ApiHandlers
    API -->|"uses Plugins"| Plugins
    API -->|"integration hooks"| Integrations

    API -->|"Prisma Client"| Prisma
    API -->|"Redis Cache/Queue"| RedisUtils
    API -->|"enqueue jobs"| QueueCtrls

    QueueCtrls -->|"jobs via Redis"| Redis
    Cron -->|"jobs via Redis"| Redis
    QueueCtrls -->|"call Embeddings Utils"| EmbUtils
    QueueCtrls -->|"call Loaders"| Loaders
    QueueCtrls -->|"call Utils"| Utils
    QueueCtrls -->|"call AI via HTTP"| AI

    Integrations -->|"calls API"| API
    Events -->|"webhook events"| Integrations

    API -->|"full-text search"| Search

    %% Click Events
    click AdminUI "https://github.com/n4ze3m/dialoqbase/tree/main/app/ui/"
    click Widget "https://github.com/n4ze3m/dialoqbase/tree/main/app/widget/"
    click Script "https://github.com/n4ze3m/dialoqbase/tree/main/app/script/"
    click API "https://github.com/n4ze3m/dialoqbase/blob/main/server/src/app.ts"
    click ApiRoutes "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/routes/api/v1/"
    click ApiHandlers "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/handlers/api/v1/"
    click Prisma "https://github.com/n4ze3m/dialoqbase/tree/main/server/prisma/"
    click QueueCtrls "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/queue/"
    click Cron "https://github.com/n4ze3m/dialoqbase/blob/main/server/src/cron/index.ts"
    click Plugins "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/plugins/"
    click Integrations "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/integration/"
    click EmbUtils "https://github.com/n4ze3m/dialoqbase/blob/main/server/src/embeddings/transformer-embedding.ts"
    click Loaders "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/loader/"
    click RedisUtils "https://github.com/n4ze3m/dialoqbase/blob/main/server/src/utils/redis.ts"
    click Utils "https://github.com/n4ze3m/dialoqbase/tree/main/server/src/utils/"

    %% Styles
    classDef frontend fill:#DDEEFF,stroke:#0366d6;
    classDef widget fill:#E6FFDD,stroke:#228B22;
    classDef backend fill:#FFD8B1,stroke:#FF8C00;
    classDef worker fill:#EBD0FF,stroke:#9B30FF;
    classDef database fill:#FFF0D1,stroke:#D2691E,shape:cylinder;
    classDef external fill:#F0F0F0,stroke:#777;
```
