Inside Chatwoot: The 20-Diagram Enterprise Architecture Master Blueprint

Chatwoot is an open-source, multi-channel customer engagement platform engineered to handle millions of real-time messages across WhatsApp, Telegram, email, and web chat widgets. Operating at high enterprise concurrency requires a decoupled architecture that balances fast HTTP webhook ingestion, durable relational persistence, sub-10ms WebSocket broadcasting, virtualized DOM timeline performance, and integrated AI agent copilot execution.

This 20-chapter interactive system breakdown deconstructs Chatwoot's complete architecture across 7 core pillars: Ingress & Edge Security, Asynchronous Queue Pipeline, Relational Persistence, Real-Time WebSockets, AI Copilot Engine, Vue.js Frontend State, and Full-Stack Observability.

Pillar I: Ingress & Edge Gateway Architecture

Section 1: Multi-Channel Webhook Ingress Gateway

Customer messages enter Chatwoot via HTTP POST webhooks dispatched by external channel APIs (e.g. Meta WhatsApp Business API, Telegram Bot API). Because external webhook senders enforce strict 5-second HTTP timeout windows, Chatwoot isolates ingress from heavy database transactions.

# app/controllers/api/v1/webhooks_controller.rb
module Api::V1
  class WebhooksController < ApplicationController
    skip_before_action :verify_authenticity_token
    before_action :verify_signature

    def process_event
      inbox = Inbox.find(params[:inbox_id])
      WhatsappEventsJob.perform_async(params.to_unsafe_hash, inbox.id)
      head :ok
    end
  end
end

Section 2: HMAC SHA256 Security & Replay Attack Defense

Before processing payloads, the WebhookVerifier concern computes an HMAC SHA256 digest using the inbox secret token and performs a constant-time security comparison (ActiveSupport::SecurityUtils.secure_compare) to prevent timing side-channel attacks.

# app/controllers/concerns/webhook_verifier.rb
module WebhookVerifier
  def verify_signature
    signature = request.headers['X-Hub-Signature-256']
    secret = Current.account.webhook_verify_token
    expected = 'sha256=' + OpenSSL::HMAC.hexdigest('sha256', secret, request.raw_post)
    head :unauthorized unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
  end
end

Section 3: Multi-Tenant Subdomain & Account Context Router

Tenant isolation is enforced via Current.account thread-local storage (ActiveSupport::CurrentAttributes), ensuring every ActiveRecord model query automatically appends WHERE account_id = ? scopes.

Pillar II: Asynchronous Job Pipeline & Event Queue Architecture

Section 4: Sidekiq Multi-Queue Processing Architecture

Once enqueued, WhatsappEventsJob payloads are pushed into Redis list structures. Sidekiq worker processes continuously poll Redis queues using the non-blocking BRPOP command with explicit queue weighting (webhooks: 5, events: 3, mailers: 1).

# config/sidekiq.yml
:queues:
  - [webhooks, 5]
  - [events, 3]
  - [default, 2]
  - [mailers, 1]

Section 5: Redis Data Structures & Connection Pool Topology

To handle high concurrent thread access, Chatwoot wraps Redis connections in a ConnectionPool manager with a size of 25 reusable sockets per process.

Section 6: Event Dispatcher & Internal Event Bus Subsystem

ActiveRecord callbacks trigger an internal event dispatcher (EventDispatcher.dispatch), decoupling core message saving from secondary tasks such as push notifications and webhook integrations.

Pillar III: Relational Persistence & Database Engineering

Section 7: PostgreSQL Schema & Relational ERD Topology

Chatwoot's primary relational schema links accounts (1:N) -> inboxes (1:N) -> conversations (1:N) -> messages under strict foreign key constraints.

-- db/schema.rb SQL Migration for Messages
CREATE TABLE messages (
    id BIGSERIAL PRIMARY KEY,
    account_id INT NOT NULL,
    inbox_id INT NOT NULL,
    conversation_id INT NOT NULL,
    message_type INT NOT NULL,
    content TEXT,
    content_attributes JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX index_messages_on_account_and_conversation ON messages (account_id, conversation_id);

Section 8: Multi-Tenant Database Isolation & Partitioning

To maintain high performance at scale, high-volume message tables utilize PostgreSQL declarative range partitioning by created_at timestamp.

Section 9: Database Indexing, Counter Caches & Performance Tuning

Composite B-tree indexes (account_id, conversation_id, id DESC) combined with GIN indexes on content_attributes JSONB columns deliver sub-millisecond query latencies.

Pillar IV: Real-Time Communication & WebSocket Architecture

Section 10: ActionCable Server Hub & Connection Lifecycle

WebSocket clients establish persistent TCP sockets with ActionCable, authenticating via pubsub_token parameters.

# app/channels/room_channel.rb
class RoomChannel < ApplicationCable::Channel
  def subscribed
    stream_from "room_#{current_user.account_id}"
  end

  def self.send_message(account_id, message)
    ActionCable.server.broadcast("room_#{account_id}", { event: 'message.created', data: message.push_event_data })
  end
end

{}

Section 11: Redis Pub/Sub Backplane & Cross-Node Scaling

ActionCable broadcasts JSON message events across a Redis Pub/Sub backplane, distributing real-time updates across multiple Rails server nodes.

Section 12: Client Stream Buffering & Backpressure Management

Client JavaScript buffers rapid incoming events, debouncing typing indicators to prevent UI frame drops.

Pillar V: AI Agent Copilot & LLM Service Engine

Section 13: AI ActionService Architecture & Capability Registry

Chatwoot embeds native AI Copilot capabilities directly into the support workspace. Support agents can request AI-generated reply suggestions, conversation summaries, or tone adjustments.

# app/services/ai/action_service.rb
module Ai
  class ActionService
    attr_reader :conversation, :action_type

    def initialize(conversation:, action_type:)
      @conversation = conversation
      @action_type = action_type
    end

    def perform
      prompt = PromptsBuilder.new(conversation: conversation, action_type: action_type).build
      OpenaiClient.new.chat(prompt)
    end
  end
end

Section 14: Dynamic Prompt Window Construction & RAG Context Assembly

PromptsBuilder formats recent conversation history into structured user/assistant messages, injecting enterprise system instructions while adhering to token budgets.

Section 15: Server-Sent Events (SSE) & Streaming Token Pipeline

LLM response tokens stream directly to the browser composer UI over SSE connections, delivering real-time agent assistance.

Pillar VI: Agent Dashboard & Frontend State Architecture

Section 16: Vue.js Single Page Application (SPA) State Architecture

The Vue.js frontend organizes client state into modular Pinia/Vuex modules (conversations, contacts, agents, inboxes).

Section 17: Virtualized Timeline Rendering & DOM Performance

To maintain 60 FPS scrolling when displaying 10,000+ message histories, Chatwoot utilizes a virtualized scroller that keeps DOM node count under 40 elements.

Section 18: Multi-Agent Workspace Collaboration & Presence Protocol

Real-time collision detection alerts agents when co-workers are viewing or typing a response to the same conversation.

Pillar VII: Operations, Observability & Security Engineering

Section 19: Full-Stack Observability & Telemetry Pipeline

Prometheus metrics export active WebSocket connection counts, Sidekiq queue latency, and DB query performance to Grafana monitoring dashboards.

Section 20: Disaster Recovery, Backup & Security Hardening

High availability is guaranteed through PostgreSQL WAL streaming replication, automated S3 encrypted snapshots, and automated GDPR data erasure workers (Contacts::DestroyService).

Master Architecture Summary Table

| Architectural Pillar | Core Technology | Primary Responsibility | SLA / Latency Metric | |---|---|---|---| | Ingress Gateway | ActionController + HMAC SHA256 | Multi-channel HTTP webhook parsing | < 5ms HTTP response | | Job Pipeline | Sidekiq + Redis BRPOP | Asynchronous worker processing | < 100ms queue execution | | Persistence | PostgreSQL + GIN Indexes | ACID message & transaction storage | < 2ms query latency | | WebSockets | ActionCable + Redis Pub/Sub | Real-time cross-node broadcasting | < 10ms WS fanout | | AI Copilot | ActionService + OpenAI SSE | Streaming LLM reply suggestions | < 50ms time-to-first-token | | Frontend State | Vue.js + Virtual Scroller | Reactive DOM timeline rendering | 60 FPS scrolling | | Observability | Prometheus + OpenTelemetry | End-to-end metrics & tracing | Real-time telemetry |