# venomlib/venom architecture

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

- Interactive diagram: https://gitdiagram.com/venomlib/venom
- Repository: https://github.com/venomlib/venom

## Overview

1. **What this repo is**
   - Venom Bot is a **Node.js library** for automating **WhatsApp Web** through **Puppeteer**.
   - The core architecture is split between a **Node host process** and a **browser-injected WhatsApp Web API** running inside the page context.

2. **Primary runtime boundary**
   - The Node side owns startup, configuration, session persistence, browser lifecycle, and the public client API.
   - The browser side runs a large injected script under `src/lib/wapi`, which talks directly to WhatsApp Web internals and the page DOM.
   - Almost all messaging, chat, group, and event operations ultimately cross this boundary.

3. **Public entrypoint and client surface**
   - The package entry points compile to `dist/index.mjs`, `dist/index.cjs`, and `dist/index.d.ts`.
   - Public consumers call `create(...)`, receive a `Whatsapp` client, and then use methods grouped by capability: sender, retriever, controls, group, profile, UI, and listeners.
   - The layered API is intentionally organized so the exported client is assembled from smaller capability layers.

4. **Startup and session initialization flow**
   - `src/controllers/initializer.ts`, `init.ts`, `browser.ts`, and `auth.ts` form the bootstrap path.
   - The flow is: load config → start or connect to Chromium via Puppeteer → validate session/token files → authenticate with QR if needed → initialize WhatsApp context → expose the client.
   - QR/login/status callbacks in the README map to this startup pipeline.

5. **Session persistence and auth boundaries**
   - Session state is persisted to token folders managed by config and checked by helpers like `check-token-file`.
   - Authentication artifacts are read/written on the Node side, while WhatsApp login state is observed in the browser context.
   - This separation is important for diagramming: token storage is local filesystem state, not a remote backend.

6. **Layered API composition**
   - The main API is built from `src/api/layers/host.layer.ts` upward through:
     - `profile.layer.ts`
     - `sender.layer.ts`
     - `listener.layer.ts`
     - `retriever.layer.ts`
     - `controls.layer.ts`
     - `ui.layer.ts`
     - `group.layer.ts`
     - `business.layer.ts`
   - Each layer adds a domain boundary: device/profile, sending, event subscription, data retrieval, chat controls, UI actions, group operations, then higher-level business methods.
   - `business.layer.ts` is the final exported “full client” shape.

7. **Browser-injected WhatsApp API (`wapi`)**
   - `src/lib/wapi` contains the code bundled for injection into WhatsApp Web.
   - It includes:
     - `functions/` for concrete operations such as send message, create group, delete messages, read chats, etc.
     - `listeners/` for event hooks like new messages, state changes, acknowledgements, reactions, participants, and live location.
     - `serializers/` for converting raw WhatsApp objects into stable library models.
     - `helper/` and `store/` for page-context utilities and access to WhatsApp’s internal store.
   - This subsystem is the “engine” that actually interacts with the WhatsApp page internals.

8. **Data flow for sending and retrieval**
   - Outbound actions usually go: public client method → API layer → helper/serializer/conversion logic → browser-injected WAPI function → WhatsApp Web.
   - Media/file operations often pass through helpers such as base64 conversion, filename/mimetype resolution, download/decrypt logic, and file cleanup.
   - Inbound data follows the reverse path: WhatsApp Web event → WAPI listener → Node callback layer → typed model objects in `src/api/model`.

9. **Events and real-time listeners**
   - Event handling is a first-class subsystem: `src/api/layers/listener.layer.ts` and `src/lib/wapi/listeners` coordinate message, state, ack, group, and call events.
   - These listeners bridge browser events back into Node callbacks such as `onMessage`, `onStateChange`, `onAck`, and group participant events.
   - This is effectively the repo’s real-time control plane.

10. **Types, models, and contracts**
   - `src/api/model` defines the domain objects and enums for chats, messages, contacts, reactions, groups, QR codes, acknowledgements, and connection states.
   - These types are shared across layers to keep the Node API, browser serialization, and user-facing callbacks aligned.
   - The repo is strongly typed and ships `.d.ts` files for consumers.

11. **Configuration and environment**
   - `src/config` holds Puppeteer and runtime options such as headless mode, browser executable path, websocket connection, proxy settings, logging, and QR behavior.
   - The configuration layer is what adapts the library to local Chrome, bundled Chromium, Docker, or remote browser sessions.
   - External dependencies that materially affect architecture are **Node.js 18+**, **Puppeteer/Chromium**, and optionally **FFmpeg** for media handling.

12. **Build and packaging architecture**
   - The repository produces both **CommonJS and ESM** builds under `dist/cjs` and `dist/esm`, plus top-level package artifacts.
   - `src/lib/wapi` is built separately from the TypeScript source, which is why there are dedicated build scripts and webpack configs under `src/lib/wapi` and `src/lib/middleware`.
   - This dual-build setup matters for diagramming because there are two compile targets: library API code and browser-injected WAPI code.

13. **Testing and examples**
   - Tests live under `test/unit`, with mocks for the WAPI store and page context.
   - The `examples/screenshot` app shows a consumer runtime, but it is not the main product boundary.
   - The tests validate helper logic, utility functions, and selected WAPI behavior rather than a separate backend service.

14. **Architectural summary for a diagram**
   - Draw the repo as a **Node library host** that initializes Puppeteer, loads tokens, injects a browser-side WhatsApp API, and then exposes a layered typed client.
   - The key boundaries are:
     - filesystem session/token storage,
     - Node controller/bootstrap logic,
     - browser-injected WhatsApp automation engine,
     - event/callback return path to the consumer.
   - There is no separate server or database; the main external systems are **WhatsApp Web** and the **local browser process**.

Main entry points: [`src/lib/wapi/wapi.js`](https://github.com/venomlib/venom/blob/master/src/lib/wapi/wapi.js) (WAPI bundle), [`src/api/layers/sender.layer.ts`](https://github.com/venomlib/venom/blob/master/src/api/layers/sender.layer.ts) (Sender layer), [`src/lib/wapi/functions/index.js`](https://github.com/venomlib/venom/blob/master/src/lib/wapi/functions/index.js) (WAPI functions), [`src/lib/wapi/listeners/index.js`](https://github.com/venomlib/venom/blob/master/src/lib/wapi/listeners/index.js) (WAPI listeners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_host["Node host"]
  node_src_index_ts["Source entry<br/>ts entry<br/>[index.ts]"]
  node_initializer_ts["Initializer<br/>bootstrap<br/>[initializer.ts]"]
  node_init_ts["Init flow<br/>startup<br/>[init.ts]"]
  node_browser_ts["Browser control<br/>puppeteer<br/>[browser.ts]"]
  node_auth_ts["Auth<br/>login/session<br/>[auth.ts]"]
  node_create_config_ts["Config builder<br/>runtime config<br/>[create-config.ts]"]
end

subgraph group_grp_api["Typed API"]
  node_host_layer_ts["Host layer<br/>api base<br/>[host.layer.ts]"]
  node_profile_layer_ts["Profile layer<br/>[profile.layer.ts]"]
  node_sender_layer_ts["Sender layer<br/>messaging<br/>[sender.layer.ts]"]
  node_retriever_layer_ts["Retriever layer<br/>read/query<br/>[retriever.layer.ts]"]
  node_controls_layer_ts["Controls layer<br/>chat control<br/>[controls.layer.ts]"]
  node_group_layer_ts["Group layer<br/>groups<br/>[group.layer.ts]"]
  node_ui_layer_ts["UI layer<br/>presence/ui<br/>[ui.layer.ts]"]
  node_listener_layer_ts["Listener layer<br/>events<br/>[listener.layer.ts]"]
  node_business_layer_ts["Full client<br/>public client<br/>[business.layer.ts]"]
  node_model_index_ts["Models<br/>contracts<br/>[index.ts]"]
end

subgraph group_grp_wapi["Browser WAPI"]
  node_wapi_js["WAPI bundle<br/>injected engine<br/>[wapi.js]"]
  node_wapi_functions_js["WAPI functions<br/>page ops<br/>[index.js]"]
  node_wapi_listeners_js["WAPI listeners<br/>event hooks<br/>[index.js]"]
  node_wapi_serializers_js["Serializers<br/>normalize<br/>[index.js]"]
  node_wapi_store_js["Store access<br/>internal store<br/>[get-store.js]"]
end

subgraph group_grp_build["Build & dist"]
  node_dist_index_mjs["Package entry<br/>dist entry<br/>[index.mjs]"]
  node_middleware_ts["Middleware<br/>bridge<br/>[middleware.ts]"]
end

node_dist_index_mjs -->|"packages"| node_src_index_ts
node_src_index_ts -->|"starts"| node_initializer_ts
node_initializer_ts -->|"loads config"| node_create_config_ts
node_initializer_ts -->|"orchestrates"| node_init_ts
node_init_ts -->|"opens browser"| node_browser_ts
node_init_ts -->|"authenticates"| node_auth_ts
node_browser_ts -->|"injects"| node_wapi_js
node_auth_ts -->|"observes state"| node_wapi_listeners_js
node_host_layer_ts -->|"extends"| node_profile_layer_ts
node_profile_layer_ts -->|"extends"| node_sender_layer_ts
node_sender_layer_ts -->|"pairs with"| node_listener_layer_ts
node_sender_layer_ts -->|"composes"| node_retriever_layer_ts
node_retriever_layer_ts -->|"composes"| node_controls_layer_ts
node_controls_layer_ts -->|"composes"| node_ui_layer_ts
node_ui_layer_ts -->|"composes"| node_group_layer_ts
node_group_layer_ts -->|"finalizes"| node_business_layer_ts
node_business_layer_ts -->|"typed by"| node_model_index_ts
node_sender_layer_ts -->|"invokes"| node_wapi_functions_js
node_retriever_layer_ts -->|"queries"| node_wapi_functions_js
node_listener_layer_ts -->|"subscribes"| node_wapi_listeners_js
node_wapi_js -->|"bundles"| node_wapi_functions_js
node_wapi_js -->|"bundles"| node_wapi_listeners_js
node_wapi_js -->|"bundles"| node_wapi_serializers_js
node_wapi_js -->|"bundles"| node_wapi_store_js
node_wapi_functions_js -->|"reads"| node_wapi_store_js
node_wapi_listeners_js -->|"emits models"| node_wapi_serializers_js
node_middleware_ts -->|"bridges"| node_wapi_js

click node_dist_index_mjs "https://github.com/venomlib/venom/blob/master/dist/index.mjs"
click node_src_index_ts "https://github.com/venomlib/venom/blob/master/src/index.ts"
click node_initializer_ts "https://github.com/venomlib/venom/blob/master/src/controllers/initializer.ts"
click node_init_ts "https://github.com/venomlib/venom/blob/master/src/controllers/init.ts"
click node_browser_ts "https://github.com/venomlib/venom/blob/master/src/controllers/browser.ts"
click node_auth_ts "https://github.com/venomlib/venom/blob/master/src/controllers/auth.ts"
click node_create_config_ts "https://github.com/venomlib/venom/blob/master/src/config/create-config.ts"
click node_host_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/host.layer.ts"
click node_profile_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/profile.layer.ts"
click node_sender_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/sender.layer.ts"
click node_retriever_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/retriever.layer.ts"
click node_controls_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/controls.layer.ts"
click node_group_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/group.layer.ts"
click node_ui_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/ui.layer.ts"
click node_listener_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/listener.layer.ts"
click node_business_layer_ts "https://github.com/venomlib/venom/blob/master/src/api/layers/business.layer.ts"
click node_model_index_ts "https://github.com/venomlib/venom/blob/master/src/api/model/index.ts"
click node_wapi_js "https://github.com/venomlib/venom/blob/master/src/lib/wapi/wapi.js"
click node_wapi_functions_js "https://github.com/venomlib/venom/blob/master/src/lib/wapi/functions/index.js"
click node_wapi_listeners_js "https://github.com/venomlib/venom/blob/master/src/lib/wapi/listeners/index.js"
click node_wapi_serializers_js "https://github.com/venomlib/venom/blob/master/src/lib/wapi/serializers/index.js"
click node_wapi_store_js "https://github.com/venomlib/venom/blob/master/src/lib/wapi/store/get-store.js"
click node_middleware_ts "https://github.com/venomlib/venom/blob/master/src/lib/middleware/middleware.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index_ts,node_initializer_ts,node_init_ts,node_browser_ts,node_auth_ts,node_create_config_ts toneBlue
class node_host_layer_ts,node_profile_layer_ts,node_sender_layer_ts,node_retriever_layer_ts,node_controls_layer_ts,node_group_layer_ts,node_ui_layer_ts,node_listener_layer_ts,node_business_layer_ts,node_model_index_ts toneAmber
class node_wapi_js,node_wapi_functions_js,node_wapi_listeners_js,node_wapi_serializers_js,node_wapi_store_js toneMint
class node_dist_index_mjs,node_middleware_ts toneRose
```

## Components

### Node host

Startup, config, browser lifecycle, and public client assembly on the Node.js side.

- [Source entry](https://github.com/venomlib/venom/blob/master/src/index.ts): ts entry · Primary TypeScript entry that wires the library together. · `src/index.ts`
- [Initializer](https://github.com/venomlib/venom/blob/master/src/controllers/initializer.ts): bootstrap · Top-level bootstrap orchestration for startup and client exposure. · `src/controllers/initializer.ts`
- [Init flow](https://github.com/venomlib/venom/blob/master/src/controllers/init.ts): startup · Coordinates startup steps and client creation. · `src/controllers/init.ts`
- [Browser control](https://github.com/venomlib/venom/blob/master/src/controllers/browser.ts): puppeteer · Launches or connects to Chromium and manages the page context. · `src/controllers/browser.ts`
- [Auth](https://github.com/venomlib/venom/blob/master/src/controllers/auth.ts): login/session · Handles QR login, session checks, and authentication state. · `src/controllers/auth.ts`
- [Config builder](https://github.com/venomlib/venom/blob/master/src/config/create-config.ts): runtime config · Builds runtime and Puppeteer options for the host process. · `src/config/create-config.ts`

### Typed API

Layered client surface and shared domain contracts.

- [Host layer](https://github.com/venomlib/venom/blob/master/src/api/layers/host.layer.ts): api base · Base client layer that anchors the layered API composition. · `src/api/layers/host.layer.ts`
- [Profile layer](https://github.com/venomlib/venom/blob/master/src/api/layers/profile.layer.ts): profile · Adds host and profile/device capability methods. · `src/api/layers/profile.layer.ts`
- [Sender layer](https://github.com/venomlib/venom/blob/master/src/api/layers/sender.layer.ts): messaging · Adds outbound messaging and media sending capabilities. · `src/api/layers/sender.layer.ts`
- [Retriever layer](https://github.com/venomlib/venom/blob/master/src/api/layers/retriever.layer.ts): read/query · Adds chat, contact, and message retrieval methods. · `src/api/layers/retriever.layer.ts`
- [Controls layer](https://github.com/venomlib/venom/blob/master/src/api/layers/controls.layer.ts): chat control · Adds chat state and control operations. · `src/api/layers/controls.layer.ts`
- [Group layer](https://github.com/venomlib/venom/blob/master/src/api/layers/group.layer.ts): groups · Adds group administration and membership operations. · `src/api/layers/group.layer.ts`
- [UI layer](https://github.com/venomlib/venom/blob/master/src/api/layers/ui.layer.ts): presence/ui · Adds presence, typing, and interface actions. · `src/api/layers/ui.layer.ts`
- [Listener layer](https://github.com/venomlib/venom/blob/master/src/api/layers/listener.layer.ts): events · Bridges browser events back into Node callbacks. · `src/api/layers/listener.layer.ts`
- [Full client](https://github.com/venomlib/venom/blob/master/src/api/layers/business.layer.ts): public client · Final exported client shape assembled from all layers. · `src/api/layers/business.layer.ts`
- [Models](https://github.com/venomlib/venom/blob/master/src/api/model/index.ts): contracts · Shared typed domain objects and enums used across the API. · `src/api/model/index.ts`

### Browser WAPI

Injected WhatsApp Web engine running inside the page context.

- [WAPI bundle](https://github.com/venomlib/venom/blob/master/src/lib/wapi/wapi.js): injected engine · Injected browser-side WhatsApp automation bundle. · `src/lib/wapi/wapi.js`
- [WAPI functions](https://github.com/venomlib/venom/blob/master/src/lib/wapi/functions/index.js): page ops · Core page-context operations for sending, retrieval, groups, and media. · `src/lib/wapi/functions/index.js`
- [WAPI listeners](https://github.com/venomlib/venom/blob/master/src/lib/wapi/listeners/index.js): event hooks · WhatsApp Web event hooks for messages, acknowledgements, groups, and state. · `src/lib/wapi/listeners/index.js`
- [Serializers](https://github.com/venomlib/venom/blob/master/src/lib/wapi/serializers/index.js): normalize · Converts raw WhatsApp objects into stable library models. · `src/lib/wapi/serializers/index.js`
- [Store access](https://github.com/venomlib/venom/blob/master/src/lib/wapi/store/get-store.js): internal store · Reads WhatsApp Web internal store objects in the page context. · `src/lib/wapi/store/get-store.js`

### Build & dist

Packaged entrypoints and generated distribution artifacts.

- [Package entry](https://github.com/venomlib/venom/blob/master/dist/index.mjs): dist entry · Published ESM entrypoint for consumers. · `dist/index.mjs`
- [Middleware](https://github.com/venomlib/venom/blob/master/src/lib/middleware/middleware.ts): bridge · Runtime middleware used by the packaged browser-side integration. · `src/lib/middleware/middleware.ts`

## Connections

- Package entry → Source entry: packages · Published artifact corresponds to the source entry.
- Source entry → Initializer: starts · Entry point hands off to bootstrap orchestration.
- Initializer → Config builder: loads config · Bootstrap builds runtime configuration first.
- Initializer → Init flow: orchestrates · Initializer coordinates the main startup flow.
- Init flow → Browser control: opens browser · Startup launches or connects to Chromium through Puppeteer.
- Init flow → Auth: authenticates · Session validation and QR/login flow happen here.
- Browser control → WAPI bundle: injects · Browser controller loads the WhatsApp automation bundle into the page.
- Auth → WAPI listeners: observes state · Login/session state is confirmed from the browser context.
- Host layer → Profile layer: extends · Base layer is augmented by profile/device capability.
- Profile layer → Sender layer: extends · Layering continues into sending capabilities.
- Sender layer → Listener layer: pairs with · Outbound methods share the client surface with event subscriptions.
- Sender layer → Retriever layer: composes · Retrieval and messaging build on the same client base.
- Retriever layer → Controls layer: composes · Chat controls extend the read/query surface.
- Controls layer → UI layer: composes · Presence and interface actions sit above chat controls.
- UI layer → Group layer: composes · Group operations are layered into the full client.
- Group layer → Full client: finalizes · Business layer is the exported full client shape.
- Full client → Models: typed by · Public API methods and callbacks use shared domain contracts.
- Sender layer → WAPI functions: invokes · Outbound calls cross into browser-side WAPI functions.
- Retriever layer → WAPI functions: queries · Read operations are executed inside the injected page engine.
- Listener layer → WAPI listeners: subscribes · Node callbacks are driven by browser event hooks.
- WAPI bundle → WAPI functions: bundles · The injected bundle includes the concrete page operations.
- WAPI bundle → WAPI listeners: bundles · The injected bundle includes event listeners.
- WAPI bundle → Serializers: bundles · Serialization helpers travel with the browser engine.
- WAPI bundle → Store access: bundles · Store access helpers are part of the page-context engine.
- WAPI functions → Store access: reads · Functions depend on WhatsApp Web internal store objects.
- WAPI listeners → Serializers: emits models · Events are normalized before crossing back to Node.
- Middleware → WAPI bundle: bridges · Packaged middleware supports the browser-side integration path.
