# ticketz-oss/ticketz architecture

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

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

## Overview

##### Project Type and Purpose
- Full-stack SaaS helpdesk/CRM that uses WhatsApp for client communication
- React SPA on the frontend, Node.js/Express backend with Sequelize (PostgreSQL), Redis caching, real-time messaging via sockets, and a Baileys-based WhatsApp bridge
- Deployed via Docker Compose with multiple env-specific Compose files and Let's Encrypt certificates

##### File Structure
- Top-level “frontend” and “backend” directories: clear separation of UI and API
- “confs” and multiple docker-compose-*.yaml files: external proxy (nginx), environment variants (local, dev, acme, cloudflare)
- Backend follows layered MVC-style:
– src/controllers → HTTP routes
– src/services → business logic
– src/models → Sequelize entities
– src/database → migrations & seeds
– src/libs/socket, wbot → real-time and WhatsApp session libs
– src/config → DB/Redis/auth/upload configs
- Frontend: React components, context providers, hooks, services (api, socket), and nginx config under “frontend/nginx”

##### README Insights
- Project uses Docker to run each component in its own container
- Requires two hostnames (frontend and backend) for ACME certificates
- Environment files for backend/frontend define API URLs, DB credentials, Redis, reCAPTCHA, etc.

##### Main Components
- Client Browser (React SPA)
- Frontend Container
– Nginx reverse-proxy serving static assets
– React App (SPA)
– WebSocket client
- Backend Container (Express API)
– HTTP REST endpoints (controllers)
– WebSocket server (socket.io via src/libs/socket)
– Business services layer
– Baileys WhatsApp service (session manager, wbot services)
– File storage for uploads/private files
- PostgreSQL Database (Sequelize)
- Redis Cache (session store, simpleObjectCache)
- External Services
– WhatsApp Web (via Baileys library)
– Payment gateways (Efi, Owen)
– Optional reCAPTCHA
- Docker Compose Network
– Bridge network linking frontend, backend, db, redis
- Let's Encrypt (cert-manager) – certificate provisioning via ACME
- Optional: PgAdmin, ngrok or cloudflare tunnels (indicated by env files)

##### Relationships and Data Flows
- User ↔ HTTPS ↔ Nginx (frontend host) ↔ React
- React ↔ REST API ↔ Nginx (API host) ↔ Express controllers
- React ↔ WebSocket ↔ Express socket server for live tickets/chats
- Express ↔ PostgreSQL (ORM) for persistence
- Express ↔ Redis for caching, token invalidation, pub/sub (optional)
- Express ↔ Baileys ↔ WhatsApp Web for messaging sessions
- Express ↔ External Payment Gateways via HTTP clients
- Docker Compose orchestrates container startup and service discovery

##### Architectural Patterns & Principles
- Layered (Controller → Service → Model)
- Domain-driven separation: announcements, campaigns, contacts, tickets, etc.
- Single API gateway (Express) with route grouping
- Containerization for environment parity
- Infrastructure as code (docker-compose, nginx confs)
- Real-time updates via WebSockets
- External integration (WhatsApp, payment gateways) abstracted into service modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        User["User Browser"]:::frontend
        subgraph "Frontend Container (ticketz-frontend)" 
            direction TB
            NginxFE["Nginx Reverse-Proxy\n(HTTPS:443)"]:::infra
            ReactApp["React SPA"]:::frontend
            WSClient["WebSocket Client"]:::frontend
        end
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        subgraph "Backend Container (ticketz-backend)" 
            direction TB
            ExpressAPI["Express API\n(server.ts/app.ts)"]:::backend
            Controllers["HTTP REST Controllers"]:::backend
            Routes["Route Definitions"]:::backend
            Services["Business Logic Services"]:::backend
            SocketServer["WebSocket Server\n(socket.io)"]:::backend
            WbotLib["Baileys WhatsApp Bridge\n(wbot libs)"]:::backend
            WbotServices["WhatsApp Service Modules"]:::backend
            ModelsDB["Sequelize Models & DB Layer"]:::backend
            FileStorage["File Storage Configuration"]:::backend
            RedisConfig["Redis Cache Configuration"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL Database\n(TCP:5432)"]:::datastore
        Redis["Redis Cache\n(port:6379)"]:::datastore
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        WhatsAppWeb["WhatsApp Web"]:::external
        PaymentAPIs["Payment Gateways (Efi, Owen)"]:::external
        ReCAPTCHA["reCAPTCHA Service"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerCompose["Docker Compose Files"]:::infra
        GlobalNginx["Global Nginx Reverse-Proxy"]:::infra
        Certs["Let's Encrypt Certificates"]:::infra
    end

    %% Connections
    User -->|HTTPS 443| NginxFE
    NginxFE --> ReactApp
    ReactApp -->|REST API HTTPS| ExpressAPI
    ReactApp -->|WebSocket WS| SocketServer

    ExpressAPI --> Controllers
    ExpressAPI --> Routes
    Routes --> Services
    Controllers --> Services
    Services --> ModelsDB
    Services --> RedisConfig
    Services --> WbotServices
    Services --> PaymentAPIs
    Services --> ReCAPTCHA
    SocketServer --> Services
    SocketServer --> RedisConfig
    WbotLib --> WbotServices
    WbotServices --> WbotLib

    ExpressAPI -->|ORM TCP 5432| Postgres
    ExpressAPI -->|Cache| Redis
    Services -->|Baileys HTTP| WhatsAppWeb
    Services -->|HTTP| PaymentAPIs
    Services -->|Validate| ReCAPTCHA

    %% Docker Compose network
    DockerCompose --- NginxFE
    DockerCompose --- ExpressAPI
    DockerCompose --- Postgres
    DockerCompose --- Redis

    GlobalNginx --- DockerCompose
    Certs --- NginxFE
    Certs --- ExpressAPI

    %% Click Events
    click NginxFE "https://github.com/ticketz-oss/ticketz/blob/main/frontend/nginx/conf.d/default.conf"
    click ReactApp "https://github.com/ticketz-oss/ticketz/tree/main/frontend/src"
    click WSClient "https://github.com/ticketz-oss/ticketz/blob/main/frontend/src/services/socket.js"
    click ExpressAPI "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/server.ts"
    click Controllers "https://github.com/ticketz-oss/ticketz/tree/main/backend/src/controllers"
    click Routes "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/routes/index.ts"
    click Services "https://github.com/ticketz-oss/ticketz/tree/main/backend/src/services"
    click SocketServer "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/libs/socket.ts"
    click WbotLib "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/libs/wbot.ts"
    click WbotServices "https://github.com/ticketz-oss/ticketz/tree/main/backend/src/services/WbotServices"
    click ModelsDB "https://github.com/ticketz-oss/ticketz/tree/main/backend/src/models"
    click FileStorage "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/config/privateFiles.ts"
    click RedisConfig "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/config/redis.ts"
    click PaymentAPIs "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/services/PaymentGatewayServices/EfiServices.ts"
    click ReCAPTCHA "https://github.com/ticketz-oss/ticketz/blob/main/backend/src/config/auth.ts"
    click DockerCompose "https://github.com/ticketz-oss/ticketz/blob/main/docker-compose-local.yaml"
    click GlobalNginx "https://github.com/ticketz-oss/ticketz/blob/main/confs/nginx-ticketz.conf"
    click Certs "https://github.com/ticketz-oss/ticketz/tree/main/backend/certs/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef datastore fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#ffccbc,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
