How gitnasr/whatsappwizard works
Project Type & Purpose
• Full‑stack “backend‐only” bot application with no user‑facing UI
• Purpose: listen to WhatsApp messages, download or convert media, send back results, provide admin controls via Telegram, expose a health‑check API, and persist events in a database.
File Structure & Key Indicators
• src/index.ts – application entry point, wires up all services
• src/routes/health.ts – Express health‑check API
• src/services – each service is a separate singleton (WhatsApp, Queue, Download, Database, Telegram, Config, Analytics, RateLimiter, Files, Redis, Express)
• prisma/schema.prisma – defines PostgreSQL models for Users, Downloads, Stickers, Errors
• bullmq + ioredis – job queue in Redis for background tasks
• telegraf – Telegram bot for admin notifications and QR codes
• whatsapp‑web.js – headless browser WhatsApp automation
Main Components
• WhatsApp Service
– Listens for incoming messages (links or images)
– Uses whatsapp‑web.js headless browser
– Emits “download request” events
• Queue Service (bullmq + Redis)
– Receives jobs from WhatsApp Service
– Pushes jobs into a Redis‑backed queue
• Worker (Download Processor)
– Consumes queue jobs
– Invokes Download Service
– Emits DownloadCompleted or DownloadFailed events
• Download Service
– Detects platform (Facebook, Instagram, TikTok, YouTube, Twitter)
– Calls platform‑specific downloader or external APIs
– Saves media temporarily via Files Service
• Files Service
– Manages local filesystem storage (e.g., public/media/)
– Cleans up after sending
• Database Service (Prisma + PostgreSQL)
– Repository pattern for Users, Downloads, Stickers, Errors
– Persists jobs, results, usage analytics, error logs
• Telegram Service
– Sends QR code, status updates, errors to admin chat
• Analytics Service (PostHog)
– Tracks usage patterns, events, errors
• Rate Limiter Service
– Guards against spam per user
• Express Health API
– Exposes /api/health endpoint showing WhatsApp connection and queue size
• Config Service
– Centralizes environment variables and settings
Relationships & Data Flows
• Incoming WhatsApp Message → WhatsApp Service → (if media download) → Queue Service → Redis
• Worker pulls from Queue → Download Service → Files Service → (on success/fail) → emits event → WhatsApp Service sends back media or error
• All events → Database Service persists records → Analytics Service logs events → Telegram Service notifies admins on key events (QR code, errors)
• Each service reads settings via Config Service
• Express API reads status from WhatsApp Service & Queue Service → replies to health check
Architectural Patterns & Principles
• Service‑Oriented / Modular design – one responsibility per service
• Singleton pattern – one instance of each core service
• Repository pattern – abstracts Prisma client access for each model
• Event‑driven & asynchronous workflow via BullMQ queue
• Separation of concerns – messaging, downloading, persistence, admin notifications