# gitnasr/whatsappwizard architecture

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

- Interactive diagram: https://gitdiagram.com/gitnasr/whatsappwizard
- Repository: https://github.com/gitnasr/whatsappwizard

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Messaging Layer
    subgraph "Messaging Layer"
        WA["WhatsApp Service"]:::core
        TE["Telegram Service"]:::external
    end

    %% Processing Layer
    subgraph "Processing Layer"
        RL["Rate Limiter Service"]:::infra
        Q["Queue Service"]:::core
        WK["Worker (Download Processor)"]:::core
        DL["Download Service"]:::core
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        FS["Files Service"]:::core
        DB["Database Service"]:::datastore
        RDS["Redis"]:::datastore
        PG["PostgreSQL"]:::datastore
    end

    %% Monitoring Layer
    subgraph "Monitoring Layer"
        CFG["Config Service"]:::infra
        API["Express Health API"]:::infra
        AN["Analytics Service"]:::external
    end

    %% Data Flows
    WA -->|DownloadJob| RL
    RL --> Q
    Q -->|Pull Job| WK
    WK -->|invokes| DL
    DL -->|saves media| FS
    FS -->|media| WA
    DL -->|DownloadCompleted/ErrorEvent| WA
    DL -->|events| DB
    DL -->|events| AN
    DL -->|errors| TE
    WA -->|QR/Error Notifications| TE
    API -->|status request| WA
    API -->|queue size request| Q
    CFG --> WA
    CFG --> Q
    CFG --> WK
    CFG --> DL
    CFG --> FS
    CFG --> DB
    CFG --> TE
    CFG --> AN
    CFG --> RL
    CFG --> API
    DB -->|stores models| PG
    Q -->|backed by| RDS

    %% Click Events
    click WA "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/WhatsApp.ts"
    click Q "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Queue.ts"
    click WK "https://github.com/gitnasr/whatsappwizard/blob/main/src/index.ts"
    click DL "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Download.ts"
    click FS "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Files.ts"
    click DB "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Database/index.ts"
    click TE "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Telegram.ts"
    click AN "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Analytics.ts"
    click RL "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Ratelimiter.ts"
    click API "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Express.ts"
    click RDS "https://github.com/gitnasr/whatsappwizard/blob/main/src/services/Redis.ts"
    click PG "https://github.com/gitnasr/whatsappwizard/blob/main/prisma/schema.prisma"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef external fill:#FFE8D0,stroke:#d66303,stroke-width:2px
    classDef datastore fill:#D0FFD6,stroke:#029D40,stroke-width:2px
    classDef infra fill:#E0E0E0,stroke:#888888,stroke-width:2px
```
