# tiledesk/tiledesk-server architecture

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

- Interactive diagram: https://gitdiagram.com/tiledesk/tiledesk-server
- Repository: https://github.com/tiledesk/tiledesk-server

## Overview

##### Project Type and Purpose
- Tiledesk-server is a monolithic Node.js/Express backend—an open-source conversational platform (live chat + chatbot engine).
- It exposes REST APIs, serves Jade/Pug views for the web widget, maintains WebSocket connections for real-time chat, and plugs into multiple messaging channels (WhatsApp, Telegram, email, etc.).
- It manages data in MongoDB, runs scheduled jobs, and loads “pubmodules” (plugin-style microservices) at runtime.

##### High-Level Component Breakdown
a. Clients
– Web widget / Admin UI (served from public/ and views/)
– Mobile apps (Android/iOS) via REST/WebSocket
– Third-party channels (Facebook, WhatsApp, Telegram, Chat21) via Webhooks & adapters
b. API Layer (Express)
– app.js + bin/www launch the HTTP + WebSocket server
– routes/ folder: defines REST endpoints & webhook receivers
– middleware/: auth, role checks, rate limits, etc.
c. Business Logic
– services/: orchestrate operations (chatbotService, messageService, emailService, scheduler, etc.)
– event/: event definitions for publish/subscribe flows
– pubmodules/: plugin modules loaded at bootstrap (routing-queue, transformer, voice-twilio, etc.)
– channels/: channel-specific SDKs & connectors (chat21, nativeauth, firebaseConnector, etc.)
d. Data Layer
– models/: Mongoose schemas & constants
– migrations/: database migrations
– config/: database, cache, email, widget, global settings
e. Real-time Engine
– websocket/: pubsub.js, subscription.js, webSocketServer.js
– services/queue & pubmodules/routing-queue: internal message bus for routing & triggers
f. Background Workers
– jobsManager.js & jobs.js: spawn worker processes for async tasks
– services/Scheduler + pubmodules/scheduler/: scheduled jobs (close unresponsive chats, etc.)
– Dockerfile-jobs: container image dedicated to job workers
g. Persistence & External Systems
– MongoDB (DATABASE_URI)
– External APIs: email SMTP, Twilio, Dialogflow/Rasa, Slack, etc.
– File storage via GridFS (services/fileGridFsService)
– Cache layer (config/cache.js + pubmodules/cache)

##### Relationships & Data Flows
- Client → HTTP Server → Routes → Services → Models → MongoDB
- Services → pubmodules (dynamic loading) → external systems (e.g., Rasa, email, SMS)
- Incoming webhook events (channels/…) → Routes → event emitters → Services → WebSocket → Client
- Services publish internal events → pubmodules/trigger → services or channels
- JobsManager/Scheduler → internal queue → Services → external APIs or DB updates
- WebSocketServer ↔ Clients for real-time message push/pull

##### Architectural Patterns & Design Principles
– MVC-style separation: routes (controller) / services (business logic) / models (DB).
– Plugin architecture: pubmodules managed by pubmodulesManager; channels folder as first-class connectors.
– Event-driven: event/*.js + pubmodules/trigger create a publish/subscribe mesh.
– Layered setup: HTTP API vs. WebSocket vs. background jobs vs. scheduler.
– Containerized deployment: multiple Dockerfiles for app, jobs, profiler; orchestrated via Docker Compose.

##### Key Details to Capture
– Exact folder-to-component mapping (e.g., routes/ → API controllers, services/ → business logic)
– Channels vs. pubmodules distinction
– WebSocket server separate flow for real-time updates
– Scheduler & jobs as separate worker processes
– Environment configuration (.env, Dockerfiles) driving container boundaries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Classes
    classDef core fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef plugin fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef data fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef external fill:#E1BEE7,stroke:#333,stroke-width:1px
    classDef client fill:#CFD8DC,stroke:#333,stroke-width:1px

    %% Clients Layer
    subgraph "Clients" 
        direction TB
        WebWidget["Web Widget / Admin UI"]:::client
        MobileApps["Mobile Apps"]:::client
        ThirdPartyChannels["Third-Party Channels"]:::client
    end

    %% HTTP API Layer
    subgraph "HTTP API Layer"
        direction TB
        ExpressServer["Express Server (app.js & bin/www)"]:::core
        Routes["REST API Controllers (routes/)"]:::core
        Middleware["Middleware (auth, rate-limit)"]:::core
    end

    %% Real-Time Layer
    subgraph "Real-Time Layer"
        direction TB
        WebSocketServer["WebSocket Server"]:::core
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        direction TB
        PubModulesManager["PubModules Manager"]:::plugin
        BusinessLogic["Business Logic Services"]:::plugin
        EventDefinitions["Event Definitions (event/)"]:::plugin
        PluginModules["PubModules"]:::plugin
        ChannelAdapters["Channel Adapters & Webhooks"]:::plugin
        InternalMessageBus["Internal Message Bus (pubmodules/queue/)"]:::plugin
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        JobsManager["Jobs Manager"]:::core
        SchedulerService["Scheduler Service"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Models["Mongoose Schemas (models/)"]:::data
        Migrations["Database Migrations (migrations/)"]:::data
        Config["Configuration (config/)"]:::data
        MongoDB["MongoDB"]:::data
        GridFS["GridFS File Storage"]:::data
        CacheLayer["Cache Layer"]:::data
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ExternalAPIs["External APIs (SMTP, Twilio, Rasa)"]:::external
    end

    %% Connections Clients to HTTP API
    WebWidget -->|HTTP / WebSocket| ExpressServer
    MobileApps -->|REST / WS| ExpressServer
    ThirdPartyChannels -->|Webhooks| Routes

    %% HTTP API Internals
    ExpressServer -->|uses| Middleware
    ExpressServer -->|routes to| Routes
    Routes -->|invoke| BusinessLogic

    %% Real-Time Flow
    BusinessLogic -->|publish events| WebSocketServer
    WebSocketServer -->|push/pull| WebWidget

    %% Plugin interactions
    BusinessLogic -->|loads| PubModulesManager
    PubModulesManager -->|manages| PluginModules
    BusinessLogic -->|calls| PluginModules
    BusinessLogic -->|calls| ChannelAdapters
    PluginModules -->|emit/subscribe| EventDefinitions
    PluginModules -->|queue messages| InternalMessageBus
    InternalMessageBus -->|dispatch| BusinessLogic

    %% Worker interactions
    JobsManager -->|spawns| SchedulerService
    SchedulerService -->|schedules| BusinessLogic
    SchedulerService -->|uses queue| InternalMessageBus

    %% Data interactions
    BusinessLogic -->|read/write| Models
    Models -->|migrations| Migrations
    BusinessLogic -->|uses| Config
    BusinessLogic -->|stores| MongoDB
    BusinessLogic -->|stores files| GridFS
    BusinessLogic -->|caches| CacheLayer

    %% External Systems
    BusinessLogic -->|calls| ExternalAPIs
    ChannelAdapters -->|webhook calls| ExternalAPIs

    %% Click Events
    click WebWidget "https://github.com/tiledesk/tiledesk-server/tree/master/public/"
    click ExpressServer "https://github.com/tiledesk/tiledesk-server/blob/master/app.js"
    click Routes "https://github.com/tiledesk/tiledesk-server/tree/master/routes/"
    click Middleware "https://github.com/tiledesk/tiledesk-server/tree/master/middleware/"
    click BusinessLogic "https://github.com/tiledesk/tiledesk-server/tree/master/services/"
    click EventDefinitions "https://github.com/tiledesk/tiledesk-server/tree/master/event/"
    click PluginModules "https://github.com/tiledesk/tiledesk-server/tree/master/pubmodules/"
    click ChannelAdapters "https://github.com/tiledesk/tiledesk-server/tree/master/channels/"
    click Models "https://github.com/tiledesk/tiledesk-server/tree/master/models/"
    click Migrations "https://github.com/tiledesk/tiledesk-server/tree/master/migrations/"
    click Config "https://github.com/tiledesk/tiledesk-server/tree/master/config/"
    click WebSocketServer "https://github.com/tiledesk/tiledesk-server/tree/master/websocket/"
    click InternalMessageBus "https://github.com/tiledesk/tiledesk-server/tree/master/pubmodules/queue/"
    click SchedulerService "https://github.com/tiledesk/tiledesk-server/blob/master/services/Scheduler.js"
    click JobsManager "https://github.com/tiledesk/tiledesk-server/blob/master/jobsManager.js"
    click GridFS "https://github.com/tiledesk/tiledesk-server/blob/master/services/fileGridFsService.js"
    click CacheLayer "https://github.com/tiledesk/tiledesk-server/blob/master/config/cache.js"
```
