# tutujaru/ticketz architecture

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

- Interactive diagram: https://gitdiagram.com/tutujaru/ticketz
- Repository: https://github.com/tutujaru/ticketz

## Overview

Ticketz is a WhatsApp-based communicator with CRM and helpdesk features. Users work through the frontend to manage contacts, conversations, tickets, queues, and campaigns; agents handle ticket/message activity while WhatsApp integrations carry customer communications. The backend separates HTTP routing and controllers from domain services and persistent models, with Socket.IO supporting live updates. The README also documents dashboard, subscription/payment, and Docker-management capabilities. Many of those modules are listed in the tree but were not sampled, so their internal connections are omitted rather than inferred.

Main entry points: [`backend/src/services/TicketServices/UpdateTicketService.ts`](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/TicketServices/UpdateTicketService.ts) (Ticket handling), [`backend/src/services/WhatsappCloudApiService.ts`](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WhatsappCloudApiService.ts) (Cloud API), [`backend/src/services/ContactServices`](https://github.com/tutujaru/ticketz/tree/main/backend/src/services/ContactServices) (Contact management), [`backend/src/server.ts`](https://github.com/tutujaru/ticketz/blob/main/backend/src/server.ts) (Backend startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_frontend["Ticketz UI<br/>[App.js]"]
end

subgraph group_http["Backend API"]
  node_contact_api["Contact endpoints"]
  node_contact_routes["Contact routes<br/>[contactRoutes.ts]"]
  node_message_api["Message endpoints"]
end

subgraph group_conversation["CRM and helpdesk"]
  node_ticket_domain["Ticket handling"]
  node_ticket_model[("Ticket records<br/>[Ticket.ts]")]
  node_contact_domain["Contact management"]
  node_contact_model[("Contact records<br/>[Contact.ts]")]
  node_message_model[("Message records<br/>[Message.ts]")]
  node_queue_model[("Queue configuration<br/>[Queue.ts]")]
  node_campaigns["Campaign management"]
  node_dashboard["Dashboard reporting"]
end

subgraph group_integrations["Messaging integrations"]
  node_whatsapp_sessions["WhatsApp sessions"]
  node_inbound_listener["Inbound messages"]
  node_cloud_api["Cloud API"]
  node_whatsapp_service[("WhatsApp accounts<br/>[Whatsapp.ts]")]
end

subgraph group_platform["Platform services"]
  node_socket["Live events<br/>[socket.ts]"]
  node_server["Backend startup<br/>[server.ts]"]
  node_database[("Database setup<br/>[index.ts]")]
  node_billing["Plans and payments"]
  node_docker["Container management"]
end

node_agent(("Agents and admins"))
node_whatsapp(("WhatsApp"))

node_agent -->|"uses"| node_frontend
node_frontend -.->|"requests contacts"| node_contact_routes
node_contact_routes -->|"routes to"| node_contact_api
node_contact_api -->|"calls"| node_contact_domain
node_contact_domain -.->|"persists contacts"| node_contact_model
node_message_api -->|"loads ticket"| node_ticket_domain
node_ticket_domain -->|"updates ticket"| node_ticket_model
node_ticket_domain -->|"uses messages"| node_message_model
node_inbound_listener -.->|"updates tickets"| node_ticket_domain
node_whatsapp_sessions -.->|"loads accounts"| node_whatsapp_service
node_whatsapp -.->|"sends messages"| node_inbound_listener
node_cloud_api -->|"creates contacts"| node_contact_domain
node_cloud_api -->|"opens tickets"| node_ticket_domain
node_cloud_api -->|"creates messages"| node_message_model
node_server -->|"initializes"| node_socket
node_server -.->|"initializes"| node_database
node_ticket_domain -->|"emits updates"| node_socket

click node_frontend "https://github.com/tutujaru/ticketz/blob/main/frontend/src/App.js"
click node_contact_api "https://github.com/tutujaru/ticketz/blob/main/backend/src/controllers/ContactController.ts"
click node_contact_routes "https://github.com/tutujaru/ticketz/blob/main/backend/src/routes/contactRoutes.ts"
click node_message_api "https://github.com/tutujaru/ticketz/blob/main/backend/src/controllers/MessageController.ts"
click node_ticket_domain "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/TicketServices/UpdateTicketService.ts"
click node_ticket_model "https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Ticket.ts"
click node_contact_domain "https://github.com/tutujaru/ticketz/tree/main/backend/src/services/ContactServices"
click node_contact_model "https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Contact.ts"
click node_message_model "https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Message.ts"
click node_queue_model "https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Queue.ts"
click node_campaigns "https://github.com/tutujaru/ticketz/tree/main/backend/src/services/CampaignService"
click node_dashboard "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/ReportService/DashboardService.ts"
click node_whatsapp_sessions "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WbotServices/StartWhatsAppSession.ts"
click node_inbound_listener "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WbotServices/wbotMessageListener.ts"
click node_cloud_api "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WhatsappCloudApiService.ts"
click node_whatsapp_service "https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Whatsapp.ts"
click node_socket "https://github.com/tutujaru/ticketz/blob/main/backend/src/libs/socket.ts"
click node_server "https://github.com/tutujaru/ticketz/blob/main/backend/src/server.ts"
click node_database "https://github.com/tutujaru/ticketz/blob/main/backend/src/database/index.ts"
click node_billing "https://github.com/tutujaru/ticketz/blob/main/backend/src/services/PaymentGatewayServices/PaymentGatewayServices.ts"
click node_docker "https://github.com/tutujaru/ticketz/tree/main/backend/src/services/DockerServices"

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_frontend toneBlue
class node_contact_api,node_contact_routes,node_message_api toneAmber
class node_ticket_domain,node_ticket_model,node_contact_domain,node_contact_model,node_message_model,node_queue_model,node_campaigns,node_dashboard toneMint
class node_whatsapp_sessions,node_inbound_listener,node_cloud_api,node_whatsapp_service toneRose
class node_socket,node_server,node_database,node_billing,node_docker,node_agent,node_whatsapp toneIndigo
```

## Components

### User interface

- [Ticketz UI](https://github.com/tutujaru/ticketz/blob/main/frontend/src/App.js): `frontend/src/App.js`

### Backend API

- [Contact endpoints](https://github.com/tutujaru/ticketz/blob/main/backend/src/controllers/ContactController.ts): `backend/src/controllers/ContactController.ts`
- [Contact routes](https://github.com/tutujaru/ticketz/blob/main/backend/src/routes/contactRoutes.ts): `backend/src/routes/contactRoutes.ts`
- [Message endpoints](https://github.com/tutujaru/ticketz/blob/main/backend/src/controllers/MessageController.ts): `backend/src/controllers/MessageController.ts`

### CRM and helpdesk

- [Ticket handling](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/TicketServices/UpdateTicketService.ts): `backend/src/services/TicketServices/UpdateTicketService.ts`
- [Ticket records](https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Ticket.ts): `backend/src/models/Ticket.ts`
- [Contact management](https://github.com/tutujaru/ticketz/tree/main/backend/src/services/ContactServices): `backend/src/services/ContactServices`
- [Contact records](https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Contact.ts): `backend/src/models/Contact.ts`
- [Message records](https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Message.ts): `backend/src/models/Message.ts`
- [Queue configuration](https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Queue.ts): `backend/src/models/Queue.ts`
- [Campaign management](https://github.com/tutujaru/ticketz/tree/main/backend/src/services/CampaignService): `backend/src/services/CampaignService`
- [Dashboard reporting](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/ReportService/DashboardService.ts): `backend/src/services/ReportService/DashboardService.ts`

### Messaging integrations

- [WhatsApp sessions](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WbotServices/StartWhatsAppSession.ts): `backend/src/services/WbotServices/StartWhatsAppSession.ts`
- [Inbound messages](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WbotServices/wbotMessageListener.ts): `backend/src/services/WbotServices/wbotMessageListener.ts`
- [Cloud API](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/WhatsappCloudApiService.ts): `backend/src/services/WhatsappCloudApiService.ts`
- [WhatsApp accounts](https://github.com/tutujaru/ticketz/blob/main/backend/src/models/Whatsapp.ts): `backend/src/models/Whatsapp.ts`

### Platform services

- [Live events](https://github.com/tutujaru/ticketz/blob/main/backend/src/libs/socket.ts): `backend/src/libs/socket.ts`
- [Backend startup](https://github.com/tutujaru/ticketz/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Database setup](https://github.com/tutujaru/ticketz/blob/main/backend/src/database/index.ts): `backend/src/database/index.ts`
- [Plans and payments](https://github.com/tutujaru/ticketz/blob/main/backend/src/services/PaymentGatewayServices/PaymentGatewayServices.ts): `backend/src/services/PaymentGatewayServices/PaymentGatewayServices.ts`
- [Container management](https://github.com/tutujaru/ticketz/tree/main/backend/src/services/DockerServices): `backend/src/services/DockerServices`

### Other components

- **Agents and admins**
- **WhatsApp**

## Connections

- Agents and admins → Ticketz UI: uses (evidence: `README.md`)
- Ticketz UI → Contact routes: requests contacts
- Contact routes → Contact endpoints: routes to (evidence: `backend/src/routes/contactRoutes.ts`)
- Contact endpoints → Contact management: calls (evidence: `backend/src/controllers/ContactController.ts`)
- Contact management → Contact records: persists contacts
- Message endpoints → Ticket handling: loads ticket (evidence: `backend/src/controllers/MessageController.ts`)
- Ticket handling → Ticket records: updates ticket (evidence: `backend/src/services/TicketServices/UpdateTicketService.ts`)
- Ticket handling → Message records: uses messages (evidence: `backend/src/services/TicketServices/UpdateTicketService.ts`)
- Inbound messages → Ticket handling: updates tickets (evidence: `backend/src/services/TicketServices/UpdateTicketService.ts`)
- WhatsApp sessions → WhatsApp accounts: loads accounts
- WhatsApp → Inbound messages: sends messages
- Cloud API → Contact management: creates contacts (evidence: `backend/src/services/WhatsappCloudApiService.ts`)
- Cloud API → Ticket handling: opens tickets (evidence: `backend/src/services/WhatsappCloudApiService.ts`)
- Cloud API → Message records: creates messages (evidence: `backend/src/services/WhatsappCloudApiService.ts`)
- Backend startup → Live events: initializes (evidence: `backend/src/server.ts`)
- Backend startup → Database setup: initializes
- Ticket handling → Live events: emits updates (evidence: `backend/src/services/TicketServices/UpdateTicketService.ts`)
