# sigalor/whatsapp-web-reveng architecture

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

- Interactive diagram: https://gitdiagram.com/sigalor/whatsapp-web-reveng
- Repository: https://github.com/sigalor/whatsapp-web-reveng

## Overview

##### Project type and purpose
- This is a full-stack, reverse-engineering tool for WhatsApp Web. It provides:
- A browser-based client UI that mimics WhatsApp Web’s login and message display
- A Node.js API/WebSocket proxy layer that exposes an HTTP server and a WebSocket endpoint to the client
- A Python backend that speaks the real WhatsApp Web protocol (handles encryption, protobuf, binary framing) and relays messages to/from the official WhatsApp Web servers

##### File structure
- Top-level:
- Dockerfile, shell.nix, package.json / requirements.txt → deployment & environment setup
- index.js & index_jsdemo.js → Node.js entry points
- `client/` → static assets (HTML, CSS/SCSS, JavaScript libraries, Bootstrap, SJCL encryption helpers, QR-code, JSON tree viewer)
- `backend/` → Python modules:
‑ `whatsapp.py` (core crypto, HKDF, AES, HMAC)
‑ `whatsapp_web_backend.py` (WebSocket server, message queue, routing to whatsapp.py)
‑ `whatsapp_binary_reader/writer.py`, `protobuf_pb2.py` (binary framing, protobuf definitions)
‑ `utilities.py` (shared helpers)
- `doc/` → protocol spec, protobuf definitions, app-architecture image
- `windows/stdint.h` → Windows build support

##### README for insights
- Describes a three-component architecture (shown in doc/img/app-architecture1000.png)
- Specifies ports used by each service and how they chain:
- Frontend served over HTTP on port 2018
- Node.js WebSocket API on port 2020
- Python WebSocket backend on port 2019
- Explains dependencies (Node v13+, Python 2.7 with pycrypto, curve25519-donna, protobuf, simple-websocket-server)

##### Main components
a. Frontend (Browser)
- Static HTML/CSS/JS served by Node.js
- WebSocketClient.js handles WS to Node
- UI libraries: BootstrapStep, UpdaterPromise, JSONTree, curve25519-js, sjcl, qrcode
b. Node.js API & Proxy Layer
- index.js starts:
- HTTP server (serves /client) on port 2018
- WebSocket server for the browser on port 2020
- Listens for browser requests, forwards calls over its WebSocket to Python backend, and relays responses back
c. Python WebSocket Backend
- whatsapp-web-backend.py starts a local WS server on port 2019
- Manages an active WebSocketClient to `wss://w[1-8].web.whatsapp.com/ws` (official WhatsApp servers)
- Contains whatsapp.py for:
- Key exchange (Curve25519, HKDF)
- AES-CBC encryption/decryption of binary messages
- HMAC validation
- Protobuf encode/decode (`whatsapp_protobuf_pb2.py`)
- Reads/writes binary/JSON, transforms WhatsApp frames into JSON messages for Node
d. External Services
- Official WhatsApp Web servers (`wss://w[1-8].web.whatsapp.com/ws`)

##### Relationships and data flow
- Browser → HTTP GET → Node.js (static files)
- Browser → WebSocket → Node.js (port 2020)
- Node.js → WebSocket → Python backend (port 2019)
- Python backend ↔ WebSocket → Official WhatsApp servers (wss://…)
- Responses flow back along the chain in reverse order

##### Architectural patterns & design principles
- Clear separation of concerns (UI vs. API proxy vs. protocol handler)
- Event-driven, message-oriented microservices (WS chain)
- Decoupled protocol handling in Python, UI logic in JS
- Environment reproducibility via Nix and Docker

##### Technologies & frameworks
- Frontend: vanilla JS, Bootstrap, sjcl (crypto), curve25519-js, qrcode, JSONTree
- Mid-tier: Node.js, `simple-websocket-server`, `nodemon`, `concurrently`, Express (serving static)
- Backend: Python 2.7, websocket-client, curve25519-donna, pycrypto, pyqrcode, protobuf
- Deployment: Docker, shell.nix, direnv

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Components
    Browser["Browser (UI)\nTechnologies: HTML/CSS/JS, Bootstrap, sjcl,\ncurve25519-js, qrcode, JSONTree"]:::frontend
    NodeAPI["Node.js API & Proxy\nTechnologies: Node.js, Express, WS\nPorts: HTTP 2018, WS 2020"]:::mid
    PythonBackend["Python WS Backend\nTechnologies: Python2.7, pycrypto,\ncurve25519-donna, protobuf\nPort: 2019"]:::backend
    WhatsAppServer["WhatsApp Web Servers\nwss://w[1-8].web.whatsapp.com/ws"]:::external

    %% Infrastructure and Docs
    subgraph "Infrastructure & Documentation"
        Infrastructure["Infrastructure\nDocker, Nix, requirements.txt"]:::infra
        Doc["Documentation & Specs"]:::doc
        Windows["Windows Support\nstdint.h"]:::infra
    end

    %% Data Flows
    Browser -->|"GET /index.html\nHTTP :2018"| NodeAPI
    Browser -->|"ws://...:2020"| NodeAPI
    NodeAPI -->|"ws://localhost:2019"| PythonBackend
    PythonBackend -->|"wss://w#.web.whatsapp.com/ws"| WhatsAppServer

    %% Click Events - Frontend
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/tree/master/client/"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/index.html"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/login-via-js-demo.html"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/css/main.css"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/css/main.scss"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/js/WebSocketClient.js"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/js/BootstrapStep.js"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/js/UpdaterPromise.js"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/blob/master/client/js/main.js"
    click Browser "https://github.com/sigalor/whatsapp-web-reveng/tree/master/client/lib/"

    %% Click Events - Node.js API
    click NodeAPI "https://github.com/sigalor/whatsapp-web-reveng/blob/master/index.js"
    click NodeAPI "https://github.com/sigalor/whatsapp-web-reveng/blob/master/index_jsdemo.js"
    click NodeAPI "https://github.com/sigalor/whatsapp-web-reveng/blob/master/package.json"
    click NodeAPI "https://github.com/sigalor/whatsapp-web-reveng/blob/master/package-lock.json"

    %% Click Events - Python Backend
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp_web_backend.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp_binary_reader.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp_binary_writer.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp_defines.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/whatsapp_protobuf_pb2.py"
    click PythonBackend "https://github.com/sigalor/whatsapp-web-reveng/blob/master/backend/utilities.py"

    %% Click Events - Infrastructure & Docs
    click Infrastructure "https://github.com/sigalor/whatsapp-web-reveng/tree/master/Dockerfile"
    click Infrastructure "https://github.com/sigalor/whatsapp-web-reveng/blob/master/shell.nix"
    click Infrastructure "https://github.com/sigalor/whatsapp-web-reveng/blob/master/requirements.txt"
    click Doc "https://github.com/sigalor/whatsapp-web-reveng/blob/master/doc/spec/def.proto"
    click Doc "https://github.com/sigalor/whatsapp-web-reveng/tree/master/doc/spec/protobuf-extractor/"
    click Doc "https://github.com/sigalor/whatsapp-web-reveng/blob/master/doc/img/app-architecture1000.png"
    click Windows "https://github.com/sigalor/whatsapp-web-reveng/blob/master/windows/stdint.h"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef mid fill:#d4edda,stroke:#333,stroke-width:1px
    classDef backend fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef infra fill:#f3e5ff,stroke:#333,stroke-width:1px
    classDef doc fill:#f0f0f0,stroke:#333,stroke-width:1px
```
