# carlinhosarena/ticketz architecture

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

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

## Overview

##### Project Type and Purpose
- Ticketz is a full-stack, containerized CRM/helpdesk application using WhatsApp as its messaging channel.
- The backend is a Node.js/TypeScript monolith (Express + Sequelize + Redis + WebSockets + Baileys), and the frontend is a React SPA served via Nginx.
- Persistence is handled by PostgreSQL; caching and real-time pub/sub by Redis; Docker Compose orchestrates services.

##### File Structure
- Top-level directories “frontend” and “backend” signal separation of concerns.
- “confs” and multiple `docker-compose-*.yaml` files define deployment modes (local, ACME SSL, Cloudflare).
- Backend follows an MVC-style layout: controllers, services, models, middleware, routes, helpers, and DB migrations/seeds.
- Frontend is a React app with contexts, hooks, components, layout, pages, and asset/public folders.
- Key config files: `.env-*-local|acme|cloudflare`, Nginx configs under `frontend/nginx`, Dockerfiles.

##### Main Components to Render
A. Client Layer
– Web browser (User)
– React SPA served by Nginx (Container: `frontend`)
B. Edge / Reverse Proxy
– Nginx handles TLS termination (Let’s Encrypt via ACME) and serves static SPA
C. API Layer (Container: `backend`)
– Express HTTP server
– REST controllers (tickets, contacts, messages, sessions, etc.)
– WebSocket endpoint (socket.io or similar in `backend/src/libs/socket.ts`)
D. Business Logic Layer
– Service classes implementing domain use-cases (Auth, TicketService, WbotServices)
– Middleware for auth, rate-limiting, compliance checks
E. Data Layer
– PostgreSQL service (Container)
– Sequelize ORM models & migrations/seeds
F. Caching & Pub/Sub
– Redis service (Container) for caching, session store, Pub/Sub to push real-time events
G. External Integrations
– WhatsApp “bridge” using Baileys library (handles sessions under `backend/src/services/WbotServices`)
– Payment gateways (Efi, Owen) invoked by PaymentGatewayServices
H. DevOps / Deployment
– Docker Compose orchestrates containers
– Nginx configs, ACME cert provisioning, environment variable files
– GitHub workflows build Docker images

##### Relationships & Data Flows
- User → HTTPS → Nginx → React SPA
- React SPA → REST API → Express controllers → Services → Models → PostgreSQL
- Express uses Redis for session/auth token management and publishes real-time events → Redis Pub/Sub → WebSocket server → React (SocketContext)
- Express invokes Baileys services → WhatsApp Web sessions → WhatsApp cloud network
- Payment flows: React SPA → API → PaymentGatewayServices → External payment provider
- Docker Compose network connects all containers

##### Architectural Patterns & Principles
- Monolithic container with layered “Controllers → Services → Models” pattern
- Containerized 12-factor app: config via environment, stateless services, logs to stdout, services bound via network
- Event-driven real-time updates via Redis Pub/Sub + WebSockets
- Clear separation between static file serving (Nginx + React) and dynamic API
- Infrastructure as code via Docker Compose, Nginx confs, env files

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        Browser["Web Browser (User)"]:::frontend
        Nginx["Nginx Reverse Proxy\n(80/443)"]:::frontend
        ReactSPA["React SPA"]:::frontend
    end
    Browser -->|HTTPS| Nginx
    Nginx -->|Serves SPA| ReactSPA

    subgraph "Backend Layer"
        Express["Express HTTP Server\n(3000)"]:::backend
        subgraph "API Layer"
            Routes["API Routes"]:::backend
            Ctrl["REST Controllers"]:::backend
        end
        subgraph "Business Logic"
            Services["Business Services"]:::backend
        end
        subgraph "Middleware"
            Middleware["Auth/Rate-Limit/Compliance"]:::backend
        end
        subgraph "Real-Time"
            Socket["WebSocket Endpoint"]:::backend
            RedisConfig["Redis Config"]:::backend
            CacheLib["Cache Library"]:::backend
        end
        WbotLib["WhatsApp Bridge Lib"]:::backend
        PaymentServices["PaymentGateway Services"]:::backend
        subgraph "Data Layer"
            Models["ORM Models & Migrations"]:::backend
        end
    end

    ReactSPA -->|REST API| Express
    Express -->|Uses| Middleware
    Express -->|Routes through| Routes
    Routes -->|Calls| Ctrl
    Ctrl -->|Invokes| Services
    Services -->|Queries| Models
    Services -->|Caches| CacheLib
    Services -->|Publishes| RedisConfig
    Services -->|Integrates| WbotLib
    Services -->|Integrates| PaymentServices
    Express -->|Upgrades to WS| Socket
    Socket -.->|Pub/Sub| RedisConfig

    subgraph "Data Stores"
        Postgres["PostgreSQL\n(5432)"]:::datastore
        Redis["Redis\n(6379)"]:::datastore
    end

    Models -->|SQL| Postgres
    RedisConfig -->|Connects| Redis

    subgraph "External Services"
        WhatsApp["WhatsApp Cloud"]:::external
        PaymentGateway["Payment Gateway Providers"]:::external
    end

    WbotLib -.->|WhatsApp API| WhatsApp
    PaymentServices -.->|External API| PaymentGateway

    subgraph "Infra / DevOps"
        DockerCompose["Docker Compose"]:::external
        CI["GitHub CI Workflow"]:::external
        EnvConfigs["Environment Configs"]:::external
        NginxConfs["Nginx Configs"]:::external
    end

    DockerCompose -->|Orchestrates| Nginx
    DockerCompose -->|Orchestrates| Express
    DockerCompose -->|Orchestrates| Postgres
    DockerCompose -->|Orchestrates| Redis

    click ReactSPA "https://github.com/carlinhosarena/ticketz/tree/main/frontend/src"
    click FrontendDockerfile "https://github.com/carlinhosarena/ticketz/tree/main/frontend/Dockerfile"
    click NginxProxy "https://github.com/carlinhosarena/ticketz/blob/main/frontend/nginx/conf.d/default.conf"
    click NginxConf "https://github.com/carlinhosarena/ticketz/blob/main/confs/nginx-ticketz.conf"
    click EnvFrontendLocal "https://github.com/carlinhosarena/ticketz/blob/main/.env-frontend-local"
    click EnvFrontendAcme "https://github.com/carlinhosarena/ticketz/blob/main/.env-frontend-acme"
    click EnvFrontendCloudflare "https://github.com/carlinhosarena/ticketz/blob/main/.env-frontend-cloudflare"
    click EnvBackendLocal "https://github.com/carlinhosarena/ticketz/blob/main/.env-backend-local"
    click EnvBackendAcme "https://github.com/carlinhosarena/ticketz/blob/main/.env-backend-acme"
    click EnvBackendCloudflare "https://github.com/carlinhosarena/ticketz/blob/main/.env-backend-cloudflare"
    click Express "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/server.ts"
    click App "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/app.ts"
    click Bootstrap "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/bootstrap.ts"
    click Controllers "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/controllers"
    click Routes "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/routes/index.ts"
    click Services "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/services"
    click Socket "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/libs/socket.ts"
    click RedisConfig "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/config/redis.ts"
    click CacheLib "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/libs/cache.ts"
    click Middleware "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/middleware"
    click Models "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/models"
    click DBMigrations "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/database/migrations"
    click DBIndex "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/database/index.ts"
    click DBSeeds "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/database/seeds"
    click Baileys "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/services/BaileysServices"
    click WbotServices "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/services/WbotServices"
    click WbotLib "https://github.com/carlinhosarena/ticketz/blob/main/backend/src/libs/wbot.ts"
    click PaymentServices "https://github.com/carlinhosarena/ticketz/tree/main/backend/src/services/PaymentGatewayServices"
    click DockerComposeLocal "https://github.com/carlinhosarena/ticketz/blob/main/docker-compose-local.yaml"
    click DockerComposeDev "https://github.com/carlinhosarena/ticketz/blob/main/docker-compose-dev.yaml"
    click DockerComposeAcme "https://github.com/carlinhosarena/ticketz/blob/main/docker-compose-acme.yaml"
    click DockerComposeCloudflare "https://github.com/carlinhosarena/ticketz/blob/main/docker-compose-cloudflare.yaml"
    click CI "https://github.com/carlinhosarena/ticketz/blob/main/ .github/workflows/build-docker.yml"
    click CertBackend "https://github.com/carlinhosarena/ticketz/tree/main/backend/certification"
    click CertsBackend "https://github.com/carlinhosarena/ticketz/tree/main/backend/certs"
    click StaticAssets "https://github.com/carlinhosarena/ticketz/tree/main/frontend/public"
    click NginxInclude1 "https://github.com/carlinhosarena/ticketz/blob/main/frontend/nginx/include.d/spa.conf"
    click NginxInclude2 "https://github.com/carlinhosarena/ticketz/blob/main/frontend/nginx/include.d/allcache.conf"
    click NginxInclude3 "https://github.com/carlinhosarena/ticketz/blob/main/frontend/nginx/include.d/nocache.conf"
    click README "https://github.com/carlinhosarena/ticketz/blob/main/README.md"
    click LICENSE "https://github.com/carlinhosarena/ticketz/blob/main/LICENSE.md"
    click TicketzPRO "https://github.com/carlinhosarena/ticketz/blob/main/Ticketz PRO.md"

    classDef frontend fill:#ADD8E6,stroke:#000
    classDef backend fill:#90EE90,stroke:#000
    classDef datastore fill:#FFA500,stroke:#000
    classDef external fill:#FFFFE0,stroke:#000
```
