How chatwoot Works: Architecture, System Design & Code Deep Dive

Project Overview

Chatwoot is an open-source customer support platform designed to help businesses manage customer conversations across many channels, like live chat on a website, email, and social media. It provides a central dashboard for support agents to interact with customers, a customer-facing chat widget for websites, and a system for managing help articles and surveys. The platform also includes an AI agent, 'Captain', to automate responses. It caters to both internal support teams (agents) and external customers, with a 'Super Admin' role for overall application configuration.

Category

tools

Difficulty

intermediete

Tech Stack

Vue.js, Ruby on Rails, ActionCable

Tags

tools

How chatwoot Works

Chatwoot is an open-source customer support platform designed to help businesses manage customer conversations across many channels, like live chat on a website, email, and social media. It provides a central dashboard for support agents to interact with customers, a customer-facing chat widget for websites, and a system for managing help articles and surveys. The platform also includes an AI agent, 'Captain', to automate responses. It caters to both internal support teams (agents) and external customers, with a 'Super Admin' role for overall application configuration.

Data Flow

Data in Chatwoot flows primarily between the frontend (Vue.js applications) and the backend (Ruby on Rails API). On the frontend, user interactions trigger actions that update local Vuex stores (e.g., `app/javascript/dashboard/store/index.js` for the dashboard, `app/javascript/widget/store/index.js` for the widget). These stores then reflect changes in the UI components (e.g., `app/javascript/dashboard/App.vue`). For persistent data, frontend actions make API calls to the Rails backend. The Rails controllers (e.g., `app/controllers/super_admin/app_configs_controller.rb`, `app/controllers/api/v1/widget/configs_controller.rb`) receive these requests, interact with Ruby models (e.g., `app/models/installation_config.rb`) to perform database operations (PostgreSQL). For real-time updates (like chat messages), the backend uses ActionCable to broadcast changes directly to connected frontend clients, bypassing traditional HTTP requests. Data sent from the backend to the frontend is often formatted into JSON using Jbuilder templates (e.g., `app/views/api/v1/models/_user.json.jbuilder`, `app/views/api/v1/models/_inbox.json.jbuilder`). Configuration data is central, flowing from YAML files (`config/installation_config.yml`) to the database (`InstallationConfig` model), then cached by `lib/global_config.rb` for quick access by both backend and frontend (via `window.globalConfig`).

Key Modules & Components

• Customer Communication Management: Handles the real-time exchange of messages between agents and customers, including sending, receiving, and displaying messages across various channels. It ensures timely and reliable communication for customer support.
  Key files: app/javascript/dashboard/App.vue, app/javascript/widget/App.vue, app/views/api/v1/models/_message.json.jbuilder
• Admin Configuration and Settings: Provides a centralized interface for super administrators to manage and configure global application settings, integrations, and user roles. It ensures the platform can be customized to fit different business needs and security requirements.
  Key files: app/controllers/super_admin/app_configs_controller.rb, app/controllers/super_admin/installation_configs_controller.rb, app/models/installation_config.rb
• Frontend Application Orchestration: Manages the overall structure and behavior of the Vue.js-based frontend applications (dashboard, widget, survey, and v3). It handles routing, state management, and the composition of UI components to deliver interactive user experiences.
  Key files: app/javascript/dashboard/App.vue, app/javascript/widget/App.vue, app/javascript/survey/App.vue
• Backend Application Core: Provides the foundational structure and runtime environment for the Ruby on Rails backend application. It defines how the application starts, loads its components, and handles incoming requests.
  Key files: config.ru, Gemfile, Rakefile
• Build and Deployment Pipeline: Automates the process of building, testing, and deploying the Chatwoot application. It ensures consistent and reliable deployments across different environments using tools like Vite and Docker.
  Key files: vite.config.ts, package.json, docker/dockerfiles/rails.Dockerfile