How ticketz-oss/ticketz works
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