# clairton/chatwoot architecture

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

- Interactive diagram: https://gitdiagram.com/clairton/chatwoot
- Repository: https://github.com/clairton/chatwoot

## Overview

Chatwoot is a self-hosted customer-engagement platform: customers contact businesses through messaging channels or the website widget; agents manage conversations and customer records in the dashboard, while teams can publish help content, run campaigns, and review reports. The map groups the principal interaction paths and major documented capabilities. The tree and route excerpt identify endpoint areas, but most controller and frontend implementations and the persistence layer were not sampled, so internal calls and storage links are intentionally limited.

Main entry points: [`app/javascript/dashboard/App.vue`](https://github.com/clairton/chatwoot/blob/uno/app/javascript/dashboard/App.vue) (Agent dashboard), [`app/controllers/api/v1/accounts/conversations_controller.rb`](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations_controller.rb) (Conversation API), [`app/controllers/api/v1/accounts/conversations/messages_controller.rb`](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations/messages_controller.rb) (Message API), [`app/dispatchers/dispatcher.rb`](https://github.com/clairton/chatwoot/blob/uno/app/dispatchers/dispatcher.rb) (Event dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engagement["Conversation management"]
  node_dashboard["Agent dashboard<br/>[App.vue]"]
  node_conversation_api["Conversation API"]
  node_message_api["Message API"]
  node_realtime["Realtime updates<br/>[room_channel.rb]"]
end

subgraph group_channels["Customer channels"]
  node_widget_api["Website widget"]
  node_public_inbox["Public inbox API"]
  node_channel_webhooks["Channel webhooks"]
  node_channel_settings["Channel setup"]
  node_integrations["Integrations"]
end

subgraph group_customer_tools["Customer tools"]
  node_contact_api["Contact API"]
  node_contact_tools["Contact tools"]
  node_custom_attributes["Custom attributes"]
end

subgraph group_knowledge["Knowledge and campaigns"]
  node_help_center["Help center"]
  node_campaigns["Campaigns"]
end

subgraph group_operations["Operations and reporting"]
  node_automation["Automation rules"]
  node_dispatch["Event dispatch<br/>[dispatcher.rb]"]
  node_reports_api["Reports API"]
  node_report_builders["Report builders<br/>[report_builder.rb]"]
  node_csat["CSAT responses"]
end

node_customer(("Customer"))
node_agent(("Agent"))
node_external_channel{{"Messaging providers"}}
node_database[("Application data")]

node_customer -->|"starts chat"| node_widget_api
node_customer -->|"opens conversation"| node_public_inbox
node_external_channel -->|"delivers events"| node_channel_webhooks
node_agent -->|"manages work"| node_dashboard
node_dashboard -->|"requests conversations"| node_conversation_api
node_dashboard -->|"sends messages"| node_message_api
node_dashboard -->|"manages contacts"| node_contact_api
node_conversation_api -.->|"reads and writes"| node_database
node_message_api -.->|"reads and writes"| node_database
node_contact_api -.->|"reads and writes"| node_database
node_widget_api -.->|"reads and writes"| node_database
node_public_inbox -.->|"reads and writes"| node_database
node_channel_webhooks -.->|"records events"| node_database
node_dashboard -->|"configures channels"| node_channel_settings
node_dashboard -->|"configures integrations"| node_integrations
node_dashboard -->|"records notes"| node_contact_tools
node_dashboard -->|"defines fields"| node_custom_attributes
node_customer -->|"reads articles"| node_help_center
node_dashboard -->|"manages content"| node_help_center
node_dashboard -->|"manages campaigns"| node_campaigns
node_dashboard -->|"configures rules"| node_automation
node_conversation_api -.->|"dispatches events"| node_dispatch
node_message_api -.->|"dispatches events"| node_dispatch
node_dispatch -.->|"broadcasts updates"| node_realtime
node_dashboard -->|"requests reports"| node_reports_api
node_reports_api -.->|"builds reports"| node_report_builders
node_dashboard -->|"reviews feedback"| node_csat

click node_dashboard "https://github.com/clairton/chatwoot/blob/uno/app/javascript/dashboard/App.vue"
click node_conversation_api "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations_controller.rb"
click node_message_api "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations/messages_controller.rb"
click node_contact_api "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/contacts_controller.rb"
click node_widget_api "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/widget/conversations_controller.rb"
click node_public_inbox "https://github.com/clairton/chatwoot/blob/uno/app/controllers/public/api/v1/inboxes/conversations_controller.rb"
click node_channel_webhooks "https://github.com/clairton/chatwoot/blob/uno/app/controllers/webhooks/whatsapp_controller.rb"
click node_channel_settings "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb"
click node_integrations "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/integrations/slack_controller.rb"
click node_contact_tools "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/contacts/notes_controller.rb"
click node_custom_attributes "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/custom_attribute_definitions_controller.rb"
click node_help_center "https://github.com/clairton/chatwoot/blob/uno/app/controllers/public/api/v1/portals/articles_controller.rb"
click node_campaigns "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/campaigns_controller.rb"
click node_automation "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/automation_rules_controller.rb"
click node_dispatch "https://github.com/clairton/chatwoot/blob/uno/app/dispatchers/dispatcher.rb"
click node_realtime "https://github.com/clairton/chatwoot/blob/uno/app/channels/room_channel.rb"
click node_reports_api "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v2/accounts/reports_controller.rb"
click node_report_builders "https://github.com/clairton/chatwoot/blob/uno/app/builders/v2/report_builder.rb"
click node_csat "https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/csat_survey_responses_controller.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_conversation_api,node_message_api,node_realtime toneBlue
class node_widget_api,node_public_inbox,node_channel_webhooks,node_channel_settings,node_integrations,node_database toneAmber
class node_contact_api,node_contact_tools,node_custom_attributes toneMint
class node_help_center,node_campaigns toneRose
class node_automation,node_dispatch,node_reports_api,node_report_builders,node_csat,node_customer,node_agent,node_external_channel toneIndigo
```

## Components

### Conversation management

- [Agent dashboard](https://github.com/clairton/chatwoot/blob/uno/app/javascript/dashboard/App.vue): `app/javascript/dashboard/App.vue`
- [Conversation API](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations_controller.rb): `app/controllers/api/v1/accounts/conversations_controller.rb`
- [Message API](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/conversations/messages_controller.rb): `app/controllers/api/v1/accounts/conversations/messages_controller.rb`
- [Realtime updates](https://github.com/clairton/chatwoot/blob/uno/app/channels/room_channel.rb): `app/channels/room_channel.rb`

### Customer channels

- [Website widget](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/widget/conversations_controller.rb): `app/controllers/api/v1/widget/conversations_controller.rb`
- [Public inbox API](https://github.com/clairton/chatwoot/blob/uno/app/controllers/public/api/v1/inboxes/conversations_controller.rb): `app/controllers/public/api/v1/inboxes/conversations_controller.rb`
- [Channel webhooks](https://github.com/clairton/chatwoot/blob/uno/app/controllers/webhooks/whatsapp_controller.rb): `app/controllers/webhooks/whatsapp_controller.rb`
- [Channel setup](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb): `app/controllers/api/v1/accounts/channels/twilio_channels_controller.rb`
- [Integrations](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/integrations/slack_controller.rb): `app/controllers/api/v1/accounts/integrations/slack_controller.rb`

### Customer tools

- [Contact API](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/contacts_controller.rb): `app/controllers/api/v1/accounts/contacts_controller.rb`
- [Contact tools](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/contacts/notes_controller.rb): `app/controllers/api/v1/accounts/contacts/notes_controller.rb`
- [Custom attributes](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/custom_attribute_definitions_controller.rb): `app/controllers/api/v1/accounts/custom_attribute_definitions_controller.rb`

### Knowledge and campaigns

- [Help center](https://github.com/clairton/chatwoot/blob/uno/app/controllers/public/api/v1/portals/articles_controller.rb): `app/controllers/public/api/v1/portals/articles_controller.rb`
- [Campaigns](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/campaigns_controller.rb): `app/controllers/api/v1/accounts/campaigns_controller.rb`

### Operations and reporting

- [Automation rules](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/automation_rules_controller.rb): `app/controllers/api/v1/accounts/automation_rules_controller.rb`
- [Event dispatch](https://github.com/clairton/chatwoot/blob/uno/app/dispatchers/dispatcher.rb): `app/dispatchers/dispatcher.rb`
- [Reports API](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v2/accounts/reports_controller.rb): `app/controllers/api/v2/accounts/reports_controller.rb`
- [Report builders](https://github.com/clairton/chatwoot/blob/uno/app/builders/v2/report_builder.rb): `app/builders/v2/report_builder.rb`
- [CSAT responses](https://github.com/clairton/chatwoot/blob/uno/app/controllers/api/v1/accounts/csat_survey_responses_controller.rb): `app/controllers/api/v1/accounts/csat_survey_responses_controller.rb`

### Other components

- **Customer**
- **Agent**
- **Messaging providers**
- **Application data**

## Connections

- Customer → Website widget: starts chat
- Customer → Public inbox API: opens conversation
- Messaging providers → Channel webhooks: delivers events
- Agent → Agent dashboard: manages work
- Agent dashboard → Conversation API: requests conversations
- Agent dashboard → Message API: sends messages
- Agent dashboard → Contact API: manages contacts
- Conversation API → Application data: reads and writes
- Message API → Application data: reads and writes
- Contact API → Application data: reads and writes
- Website widget → Application data: reads and writes
- Public inbox API → Application data: reads and writes
- Channel webhooks → Application data: records events
- Agent dashboard → Channel setup: configures channels
- Agent dashboard → Integrations: configures integrations
- Agent dashboard → Contact tools: records notes
- Agent dashboard → Custom attributes: defines fields
- Customer → Help center: reads articles
- Agent dashboard → Help center: manages content
- Agent dashboard → Campaigns: manages campaigns
- Agent dashboard → Automation rules: configures rules
- Conversation API → Event dispatch: dispatches events
- Message API → Event dispatch: dispatches events
- Event dispatch → Realtime updates: broadcasts updates
- Agent dashboard → Reports API: requests reports
- Reports API → Report builders: builds reports
- Agent dashboard → CSAT responses: reviews feedback