# diazzaid/whatsapp-api-venom architecture

> Architecture diagram of the GitHub repository diazzaid/whatsapp-api-venom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/diazzaid/whatsapp-api-venom
- Repository: https://github.com/diazzaid/whatsapp-api-venom

## Overview

##### Project type and purpose
- This is a full-stack HTTP API server built with NestJS (TypeScript) that wraps the Venom library to expose WhatsApp messaging features over REST.
- The README confirms it serves Swagger/OpenAPI docs and implements controllers for sending messages, screenshots, device info, etc.

##### File structure
- Top-level:
- package.json, tsconfig.json, nest-cli.json – show Node/NestJS configuration
- docs/ – static Swagger UI and OpenAPI spec
- examples/ – client-side Python curl example
- src/ – the NestJS application
- src/api: controllers for each REST resource (chatting.controller.ts, screenshot.controller.ts, device.controller.ts) and a DTO file.
- src/whatsapp.service.ts: encapsulates calls to the Venom library.
- src/config.service.ts: holds environment-specific paths (e.g., token storage).
- src/app.module.ts and src/main.ts: NestJS module and entrypoint.

##### Key insights from README
- Project serves on http://localhost:3000, auto-generates Swagger UI under docs.
- Uses Venom to spawn a headless browser session for WhatsApp Web, stores session tokens on disk.
- Exposes endpoints for messaging, media, contacts, screenshots, and more.

##### Main components
a. API Gateway (NestJS HTTP server)
- Controllers layer (ChattingController, DeviceController, ScreenshotController)
- Service layer (WhatsappService)
- ConfigService for environment and file‐path settings
b. Venom Library
- Underlying WhatsApp Web headless-browser client
c. Token Storage
- Local file system directory (e.g., /tmp/whatsapp-files or Windows path)
d. Swagger UI / OpenAPI Docs
- Static files served from docs/
e. Clients
- curl/HTTP clients, Swagger UI browser, example Python script

##### Relationships and interactions
- Client → HTTP request → NestJS Controller → calls WhatsappService → Venom API → WhatsApp Web
- Venom API reads/writes session tokens in file system
- NestJS serves Swagger UI assets and OpenAPI JSON from docs/
- ConfigService injects environment‐specific settings into WhatsappService

##### Architectural patterns & design principles
- Layered pattern: Controllers → Services → External Library
- Dependency Injection (NestJS modules/services)
- Configuration-as-Service (ConfigService)
- DTOs for request validation

##### Technologies & frameworks
- Node.js + NestJS (TypeScript)
- Venom (WhatsApp Web automation)
- Swagger/OpenAPI for documentation
- File system for token persistence

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        direction TB
        HTTPClient["HTTP Client"]:::external
        SwaggerBrowser["Swagger UI Browser"]:::external
        ExampleClient["Example Script"]:::external
    end

    %% Documentation
    subgraph "Documentation/UI" 
        direction TB
        SwaggerUI["Swagger UI Static Files"]:::docs
        OpenAPISpec["OpenAPI JSON Spec"]:::docs
    end

    %% API Server
    subgraph "API Gateway (NestJS HTTP Server)" 
        direction TB
        MainApp["Main (src/main.ts)"]:::http
        AppModule["App Module (src/app.module.ts)"]:::http

        subgraph "Controllers Layer"
            direction TB
            ChattingController["ChattingController"]:::http
            DeviceController["DeviceController"]:::http
            ScreenshotController["ScreenshotController"]:::http
        end

        DTOs["DTOs (src/api/all.dto.ts)"]:::http
        ConfigService["ConfigService"]:::business
        WhatsappService["WhatsappService"]:::business
    end

    %% External Systems
    subgraph "WhatsApp Integration"
        direction TB
        VenomLib["Venom Library"]:::external
        WhatsAppWeb["WhatsApp Web"]:::external
    end

    %% Storage
    TokenStorage["Token Storage (File System)"]:::storage

    %% Config and Build Files
    subgraph "Project Configurations"
        direction TB
        NestCLIConfig["nest-cli.json"]:::docs
        TSConfig1["tsconfig.json"]:::docs
        TSConfig2["tsconfig.build.json"]:::docs
        PackageJSON["package.json"]:::docs
    end

    %% Interactions
    HTTPClient -->|HTTP Request| ChattingController
    HTTPClient -->|HTTP Request| DeviceController
    HTTPClient -->|HTTP Request| ScreenshotController

    ChattingController -->|validate DTO| DTOs
    DeviceController -->|validate DTO| DTOs
    ScreenshotController -->|validate DTO| DTOs

    ChattingController -->|calls| WhatsappService
    DeviceController -->|calls| WhatsappService
    ScreenshotController -->|calls| WhatsappService

    AppModule -->|imports| ChattingController
    AppModule -->|imports| DeviceController
    AppModule -->|imports| ScreenshotController
    AppModule -->|provides| WhatsappService
    AppModule -->|provides| ConfigService

    MainApp -->|bootstraps| AppModule

    WhatsappService -->|uses| VenomLib
    WhatsappService -->|reads/writes tokens| TokenStorage
    WhatsappService -->|gets config| ConfigService

    VenomLib -->|controls| WhatsAppWeb

    SwaggerBrowser -->|loads UI| SwaggerUI
    SwaggerBrowser -->|loads spec| OpenAPISpec
    HTTPClient -->|retrieves spec| OpenAPISpec

    ExampleClient -->|sends HTTP| HTTPClient

    %% Click events
    click MainApp "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/main.ts"
    click AppModule "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/app.module.ts"
    click ChattingController "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/api/chatting.controller.ts"
    click DeviceController "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/api/device.controller.ts"
    click ScreenshotController "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/api/screenshot.controller.ts"
    click DTOs "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/api/all.dto.ts"
    click WhatsappService "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/whatsapp.service.ts"
    click ConfigService "https://github.com/diazzaid/whatsapp-api-venom/blob/main/src/config.service.ts"
    click SwaggerUI "https://github.com/diazzaid/whatsapp-api-venom/tree/main/docs/"
    click OpenAPISpec "https://github.com/diazzaid/whatsapp-api-venom/blob/main/docs/openapi.json"
    click ExampleClient "https://github.com/diazzaid/whatsapp-api-venom/blob/main/examples/echo.py"
    click NestCLIConfig "https://github.com/diazzaid/whatsapp-api-venom/blob/main/nest-cli.json"
    click TSConfig1 "https://github.com/diazzaid/whatsapp-api-venom/blob/main/tsconfig.json"
    click TSConfig2 "https://github.com/diazzaid/whatsapp-api-venom/blob/main/tsconfig.build.json"
    click PackageJSON "https://github.com/diazzaid/whatsapp-api-venom/blob/main/package.json"

    %% Styles
    classDef http fill:#cce5ff,stroke:#333,color:#000
    classDef business fill:#d4edda,stroke:#333,color:#000
    classDef external fill:#ffe5b4,stroke:#333,color:#000
    classDef storage fill:#e2e3e5,stroke:#333,color:#000
    classDef docs fill:#f3e5ff,stroke:#333,color:#000
```
