# mhd-afrij/whatsapp_crm architecture

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

- Interactive diagram: https://gitdiagram.com/mhd-afrij/whatsapp_crm
- Repository: https://github.com/mhd-afrij/whatsapp_crm

## Overview

CRM-WhatsApp is a multi-service, WhatsApp-first team CRM. Users work through the Next.js dashboard to manage shared conversations, contacts, leads, deals, campaigns, tasks, reports, and workspace settings; the Laravel API provides CRM behavior, while the gateway owns WhatsApp connectivity and WhatsApp-origin message data. The gateway persists and processes messages, notifies the backend, and supports realtime events. Edges are limited to relationships shown in the README or supplied source evidence; unsampled capabilities are represented at subsystem level rather than by inferred call chains.

Main entry points: [`backend/app/Http/Controllers/Api/V1`](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1) (CRM REST API), [`whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/inbound-pipeline.ts) (Inbound message pipeline), [`frontend/src/app/(dashboard)`](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/app/(dashboard)) (CRM dashboard), [`backend/app/Http/Controllers/Api/V1/ConversationController.php`](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Http/Controllers/Api/V1/ConversationController.php) (Conversation management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_dashboard["CRM dashboard"]
  node_frontend_api["API client and hooks"]
  node_inbox_ui["Shared inbox UI"]
end

subgraph group_crm["CRM and collaboration"]
  node_crm_api["CRM REST API"]
  node_auth["Auth and permissions"]
  node_conversation["Conversation management"]
  node_pipeline["Pipeline and deal stages"]
  node_contact_link["Contact auto-linking"]
  node_crm_entities[("CRM domain records")]
  node_workspace[("Workspace and RBAC<br/>[Workspace.php]")]
  node_campaigns_tasks["Campaigns and tasks"]
  node_reports_analytics["Reports and analytics"]
  node_admin_settings["Settings and administration"]
end

subgraph group_gateway["WhatsApp gateway"]
  node_gateway_routes["Gateway API routes"]
  node_connection_manager["Connection manager"]
  node_baileys["WhatsApp socket<br/>[baileys-socket.ts]"]
  node_inbound["Inbound message pipeline"]
  node_message_repo["Message repository"]
  node_gateway_api_client["Backend notification client<br/>[laravel-client.ts]"]
end

subgraph group_state["Persistence and realtime"]
  node_socket_events["Realtime event server<br/>[socket-server.ts]"]
  node_media_storage["Message media storage<br/>[storage.ts]"]
  node_mysql[("Gateway MySQL access<br/>[mysql.ts]")]
  node_redis[("Redis")]
end

node_agent(("Agent or admin"))
node_whatsapp(("WhatsApp service"))

node_agent -->|"uses"| node_dashboard
node_dashboard -.->|"requests data"| node_frontend_api
node_dashboard -.->|"shows inbox"| node_inbox_ui
node_frontend_api -->|"calls REST API"| node_crm_api
node_crm_api -.->|"protects routes"| node_auth
node_crm_api -.->|"routes inbox requests"| node_conversation
node_crm_api -.->|"routes pipeline requests"| node_pipeline
node_crm_api -.->|"serves CRM features"| node_campaigns_tasks
node_crm_api -.->|"serves reporting"| node_reports_analytics
node_crm_api -.->|"serves administration"| node_admin_settings
node_conversation -->|"links contacts"| node_contact_link
node_conversation -->|"reads and writes"| node_crm_entities
node_pipeline -->|"creates stages"| node_crm_entities
node_workspace -->|"owns workspace data"| node_crm_entities
node_whatsapp -->|"connects through"| node_baileys
node_gateway_routes -->|"dispatches actions"| node_connection_manager
node_connection_manager -.->|"manages socket"| node_baileys
node_baileys -.->|"delivers messages"| node_inbound
node_inbound -->|"persists messages"| node_message_repo
node_inbound -->|"notifies backend"| node_gateway_api_client
node_inbound -->|"emits message event"| node_socket_events
node_message_repo -->|"queries and writes"| node_mysql
node_gateway_routes -->|"reads media"| node_media_storage
node_socket_events -->|"uses adapter"| node_redis
node_gateway_api_client -->|"notifies messages"| node_crm_api

click node_dashboard "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/app/(dashboard)"
click node_frontend_api "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/lib"
click node_inbox_ui "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/components/inbox"
click node_crm_api "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1"
click node_auth "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Middleware"
click node_conversation "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Http/Controllers/Api/V1/ConversationController.php"
click node_pipeline "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Http/Controllers/Api/V1/PipelineController.php"
click node_contact_link "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Services/ContactAutoLinker.php"
click node_crm_entities "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Models"
click node_workspace "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Models/Workspace.php"
click node_campaigns_tasks "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1"
click node_reports_analytics "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1"
click node_admin_settings "https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1"
click node_gateway_routes "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/routes/internal-whatsapp.routes.ts"
click node_connection_manager "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/connection-manager.ts"
click node_baileys "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/baileys-socket.ts"
click node_inbound "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/inbound-pipeline.ts"
click node_message_repo "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/message-repository.ts"
click node_gateway_api_client "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/laravel-client.ts"
click node_socket_events "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/socket-server.ts"
click node_media_storage "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/storage.ts"
click node_mysql "https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/mysql.ts"

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_frontend_api,node_inbox_ui toneBlue
class node_crm_api,node_auth,node_conversation,node_pipeline,node_contact_link,node_crm_entities,node_workspace,node_campaigns_tasks,node_reports_analytics,node_admin_settings toneAmber
class node_gateway_routes,node_connection_manager,node_baileys,node_inbound,node_message_repo,node_gateway_api_client toneMint
class node_socket_events,node_media_storage,node_mysql,node_redis toneRose
class node_agent,node_whatsapp toneIndigo
```

## Components

### User interface

- [CRM dashboard](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [API client and hooks](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/lib): `frontend/src/lib`
- [Shared inbox UI](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/frontend/src/components/inbox): `frontend/src/components/inbox`

### CRM and collaboration

- [CRM REST API](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1): `backend/app/Http/Controllers/Api/V1`
- [Auth and permissions](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Middleware): `backend/app/Http/Middleware`
- [Conversation management](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Http/Controllers/Api/V1/ConversationController.php): `backend/app/Http/Controllers/Api/V1/ConversationController.php`
- [Pipeline and deal stages](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Http/Controllers/Api/V1/PipelineController.php): `backend/app/Http/Controllers/Api/V1/PipelineController.php`
- [Contact auto-linking](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Services/ContactAutoLinker.php): `backend/app/Services/ContactAutoLinker.php`
- [CRM domain records](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Models): `backend/app/Models`
- [Workspace and RBAC](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/backend/app/Models/Workspace.php): `backend/app/Models/Workspace.php`
- [Campaigns and tasks](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1): `backend/app/Http/Controllers/Api/V1`
- [Reports and analytics](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1): `backend/app/Http/Controllers/Api/V1`
- [Settings and administration](https://github.com/mhd-afrij/whatsapp_crm/tree/develop/backend/app/Http/Controllers/Api/V1): `backend/app/Http/Controllers/Api/V1`

### WhatsApp gateway

- [Gateway API routes](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/routes/internal-whatsapp.routes.ts): `whatsapp-gateway/src/routes/internal-whatsapp.routes.ts`
- [Connection manager](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/connection-manager.ts): `whatsapp-gateway/src/whatsapp/connection-manager.ts`
- [WhatsApp socket](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/baileys-socket.ts): `whatsapp-gateway/src/whatsapp/baileys-socket.ts`
- [Inbound message pipeline](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/inbound-pipeline.ts): `whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`
- [Message repository](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/whatsapp/message-repository.ts): `whatsapp-gateway/src/whatsapp/message-repository.ts`
- [Backend notification client](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/laravel-client.ts): `whatsapp-gateway/src/lib/laravel-client.ts`

### Persistence and realtime

- [Realtime event server](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/socket-server.ts): `whatsapp-gateway/src/lib/socket-server.ts`
- [Message media storage](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/storage.ts): `whatsapp-gateway/src/lib/storage.ts`
- [Gateway MySQL access](https://github.com/mhd-afrij/whatsapp_crm/blob/develop/whatsapp-gateway/src/lib/mysql.ts): `whatsapp-gateway/src/lib/mysql.ts`
- **Redis**

### Other components

- **Agent or admin**
- **WhatsApp service**

## Connections

- Agent or admin → CRM dashboard: uses
- CRM dashboard → API client and hooks: requests data
- CRM dashboard → Shared inbox UI: shows inbox
- API client and hooks → CRM REST API: calls REST API
- CRM REST API → Auth and permissions: protects routes
- CRM REST API → Conversation management: routes inbox requests
- CRM REST API → Pipeline and deal stages: routes pipeline requests
- CRM REST API → Campaigns and tasks: serves CRM features
- CRM REST API → Reports and analytics: serves reporting
- CRM REST API → Settings and administration: serves administration
- Conversation management → Contact auto-linking: links contacts (evidence: `backend/app/Http/Controllers/Api/V1/ConversationController.php`)
- Conversation management → CRM domain records: reads and writes (evidence: `backend/app/Http/Controllers/Api/V1/ConversationController.php`)
- Pipeline and deal stages → CRM domain records: creates stages (evidence: `backend/app/Http/Controllers/Api/V1/PipelineController.php`)
- Workspace and RBAC → CRM domain records: owns workspace data (evidence: `backend/app/Models/Workspace.php`)
- WhatsApp service → WhatsApp socket: connects through
- Gateway API routes → Connection manager: dispatches actions (evidence: `whatsapp-gateway/src/routes/internal-whatsapp.routes.ts`)
- Connection manager → WhatsApp socket: manages socket
- WhatsApp socket → Inbound message pipeline: delivers messages (evidence: `whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`)
- Inbound message pipeline → Message repository: persists messages (evidence: `whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`)
- Inbound message pipeline → Backend notification client: notifies backend (evidence: `whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`)
- Inbound message pipeline → Realtime event server: emits message event (evidence: `whatsapp-gateway/src/whatsapp/inbound-pipeline.ts`)
- Message repository → Gateway MySQL access: queries and writes (evidence: `whatsapp-gateway/src/whatsapp/message-repository.ts`)
- Gateway API routes → Message media storage: reads media (evidence: `whatsapp-gateway/src/routes/internal-whatsapp.routes.ts`)
- Realtime event server → Redis: uses adapter (evidence: `whatsapp-gateway/src/lib/socket-server.ts`)
- Backend notification client → CRM REST API: notifies messages
