# vitorpaimio/chatwoot-kanban architecture

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

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

## Overview

Chatwoot Kanban embeds a pipeline, shared tasks, conversation context, history, and metrics in the team’s Chatwoot session. Users work through the browser UI and FastAPI; account-scoped data is stored locally, while a worker processes webhook deliveries and mirrors selected attributes to Chatwoot. The README also documents a CLI installer for deploying, activating, updating, and removing the integration. Links reflect documented behavior and sampled source; unsampled route and installer internals are represented conservatively.

Main entry points: [`app/main.py`](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/main.py) (FastAPI app), [`app/database.py`](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/database.py) (PostgreSQL), [`app/routers/workspace.py`](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/workspace.py) (Workspace API), [`app/routers/metrics.py`](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/metrics.py) (Metrics API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Embedded interface"]
  node_kanban_ui["Kanban UI<br/>[kanban.js]"]
  node_metrics_ui["Metrics UI<br/>[metricas.js]"]
  node_tasks_ui["Tasks UI<br/>[tarefas.js]"]
end

subgraph group_api["API and domain"]
  node_web_app["FastAPI app<br/>[main.py]"]
  node_workspace["Workspace API<br/>[workspace.py]"]
  node_metrics_api["Metrics API<br/>[metrics.py]"]
  node_provisioning_api["Provisioning API<br/>[provisioning.py]"]
  node_domain_services["Kanban services<br/>[services.py]"]
  node_metrics_service["Metrics service<br/>[service.py]"]
end

subgraph group_runtime["State and integration"]
  node_attribute_setup["Attribute provisioning<br/>[attributes.py]"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
  node_event_hub["SSE event hub<br/>[events.py]"]
  node_worker["Sync worker<br/>[worker.py]"]
  node_chatwoot_client["Chatwoot client<br/>[chatwoot_client.py]"]
end

subgraph group_install["Installation lifecycle"]
  node_installer_cli["Installer CLI<br/>[__main__.py]"]
  node_installer_lifecycle["Install lifecycle<br/>[lifecycle.py]"]
end

node_team(("Chatwoot team"))
node_chatwoot_api["Chatwoot API"]
node_docker["Docker host"]

node_team -->|"uses board"| node_kanban_ui
node_team -->|"views metrics"| node_metrics_ui
node_team -->|"manages tasks"| node_tasks_ui
node_web_app -->|"serves assets"| node_kanban_ui
node_web_app -->|"serves pages"| node_metrics_ui
node_web_app -->|"serves pages"| node_tasks_ui
node_kanban_ui -->|"calls API"| node_workspace
node_metrics_ui -->|"calls API"| node_metrics_api
node_tasks_ui -->|"calls API"| node_workspace
node_web_app -->|"mounts router"| node_workspace
node_web_app -->|"mounts router"| node_metrics_api
node_web_app -->|"mounts router"| node_provisioning_api
node_workspace -->|"reads and writes"| node_postgres
node_workspace -->|"delegates actions"| node_domain_services
node_domain_services -->|"records changes"| node_postgres
node_domain_services -->|"notifies changes"| node_event_hub
node_metrics_api -->|"requests metrics"| node_metrics_service
node_metrics_api -->|"queries account data"| node_postgres
node_metrics_service -->|"caches results"| node_postgres
node_metrics_service -->|"fetches options"| node_chatwoot_client
node_provisioning_api -->|"provisions attributes"| node_attribute_setup
node_attribute_setup -->|"manages definitions"| node_chatwoot_client
node_event_hub -->|"listens for events"| node_postgres
node_worker -->|"processes queue"| node_postgres
node_worker -->|"applies updates"| node_domain_services
node_worker -->|"syncs remote state"| node_chatwoot_client
node_chatwoot_client -->|"sends requests"| node_chatwoot_api
node_chatwoot_api -->|"posts webhooks"| node_web_app
node_team -->|"runs setup"| node_installer_cli
node_installer_cli -->|"selects operation"| node_installer_lifecycle
node_installer_lifecycle -->|"deploys integration"| node_docker

click node_kanban_ui "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/kanban.js"
click node_metrics_ui "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/metricas.js"
click node_tasks_ui "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/tarefas.js"
click node_web_app "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/main.py"
click node_workspace "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/workspace.py"
click node_metrics_api "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/metrics.py"
click node_provisioning_api "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/provisioning.py"
click node_domain_services "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/services.py"
click node_metrics_service "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/metrics/service.py"
click node_attribute_setup "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/provisioning/attributes.py"
click node_postgres "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/database.py"
click node_event_hub "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/events.py"
click node_worker "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/worker.py"
click node_chatwoot_client "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/chatwoot_client.py"
click node_installer_cli "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/installer/__main__.py"
click node_installer_lifecycle "https://github.com/vitorpaimio/chatwoot-kanban/blob/main/installer/lifecycle.py"

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_kanban_ui,node_metrics_ui,node_tasks_ui toneBlue
class node_web_app,node_workspace,node_metrics_api,node_provisioning_api,node_domain_services,node_metrics_service toneAmber
class node_attribute_setup,node_postgres,node_event_hub,node_worker,node_chatwoot_client,node_chatwoot_api toneMint
class node_installer_cli,node_installer_lifecycle toneRose
class node_team,node_docker toneIndigo
```

## Components

### Embedded interface

- [Kanban UI](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/kanban.js): `app/static/kanban.js`
- [Metrics UI](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/metricas.js): `app/static/metricas.js`
- [Tasks UI](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/static/tarefas.js): `app/static/tarefas.js`

### API and domain

- [FastAPI app](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/main.py): `app/main.py`
- [Workspace API](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/workspace.py): `app/routers/workspace.py`
- [Metrics API](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/metrics.py): `app/routers/metrics.py`
- [Provisioning API](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/routers/provisioning.py): `app/routers/provisioning.py`
- [Kanban services](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/services.py): `app/services.py`
- [Metrics service](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/metrics/service.py): `app/metrics/service.py`

### State and integration

- [Attribute provisioning](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/provisioning/attributes.py): `app/provisioning/attributes.py`
- [PostgreSQL](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/database.py): `app/database.py`
- [SSE event hub](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/events.py): `app/events.py`
- [Sync worker](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/worker.py): `app/worker.py`
- [Chatwoot client](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/app/chatwoot_client.py): `app/chatwoot_client.py`

### Installation lifecycle

- [Installer CLI](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/installer/__main__.py): `installer/__main__.py`
- [Install lifecycle](https://github.com/vitorpaimio/chatwoot-kanban/blob/main/installer/lifecycle.py): `installer/lifecycle.py`

### Other components

- **Chatwoot team**
- **Chatwoot API**
- **Docker host**

## Connections

- Chatwoot team → Kanban UI: uses board
- Chatwoot team → Metrics UI: views metrics
- Chatwoot team → Tasks UI: manages tasks
- FastAPI app → Kanban UI: serves assets
- FastAPI app → Metrics UI: serves pages
- FastAPI app → Tasks UI: serves pages
- Kanban UI → Workspace API: calls API
- Metrics UI → Metrics API: calls API
- Tasks UI → Workspace API: calls API
- FastAPI app → Workspace API: mounts router
- FastAPI app → Metrics API: mounts router
- FastAPI app → Provisioning API: mounts router
- Workspace API → PostgreSQL: reads and writes
- Workspace API → Kanban services: delegates actions
- Kanban services → PostgreSQL: records changes
- Kanban services → SSE event hub: notifies changes
- Metrics API → Metrics service: requests metrics
- Metrics API → PostgreSQL: queries account data
- Metrics service → PostgreSQL: caches results
- Metrics service → Chatwoot client: fetches options
- Provisioning API → Attribute provisioning: provisions attributes
- Attribute provisioning → Chatwoot client: manages definitions
- SSE event hub → PostgreSQL: listens for events
- Sync worker → PostgreSQL: processes queue
- Sync worker → Kanban services: applies updates
- Sync worker → Chatwoot client: syncs remote state
- Chatwoot client → Chatwoot API: sends requests
- Chatwoot API → FastAPI app: posts webhooks
- Chatwoot team → Installer CLI: runs setup
- Installer CLI → Install lifecycle: selects operation
- Install lifecycle → Docker host: deploys integration