# tomer8007/whatsapp-web-incognito architecture

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

- Interactive diagram: https://gitdiagram.com/tomer8007/whatsapp-web-incognito
- Repository: https://github.com/tomer8007/whatsapp-web-incognito

## Overview

WhatsApp Web Incognito is a browser extension that intercepts WhatsApp Web’s WebSocket traffic to suppress selected presence and receipt updates, while adding message recovery, device-origin indicators, status downloads, and controls for configuring these behaviors. The documented runtime path is frame interception, decryption when needed, binary decoding, stanza inspection, and blocking or altering selected traffic. The graph also shows settings and UI, plus the parsing and encryption layers. Some subsystem links are based on README statements; unsampled source connections are omitted.

Main entry points: [`core/interception.js`](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/interception.js) (Frame interception), [`core/node_handler.js`](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/node_handler.js) (Node handling), [`core/ws_hook.js`](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ws_hook.js) (WebSocket hook), [`core/multi_device.js`](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/multi_device.js) (Multi-device crypto)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interception["Traffic interception"]
  node_ws["WebSocket hook<br/>[ws_hook.js]"]
  node_inject["Page injection<br/>[core_injection.js]"]
  node_interception_logic["Frame interception<br/>[interception.js]"]
end

subgraph group_protocol["Protocol handling"]
  node_handler["Node handling<br/>[node_handler.js]"]
  node_multidevice["Multi-device crypto<br/>[multi_device.js]"]
  node_binary_reader["Binary reader<br/>[binary_reader.js]"]
  node_binary_writer["Binary writer<br/>[binary_writer.js]"]
  node_node_codec["Node codec"]
  node_proto_schema["Message schema<br/>[WAProto.proto]"]
  node_whisper_proto["Whisper protocol"]
  node_legacy_single["Legacy single-device"]
  node_legacy_reader["Legacy node reader<br/>[node_reader.js]"]
  node_legacy_writer["Legacy node writer<br/>[node_writer.js]"]
  node_compression["Compression utility<br/>[pako.js]"]
end

subgraph group_features["User features"]
  node_restore_ui["Message recovery UI<br/>[ui.js]"]
  node_injected_ui["Injected page UI<br/>[injected_ui.js]"]
  node_status_download["Status downloads<br/>[status_download.js]"]
end

subgraph group_settings["Settings and UI"]
  node_background["Preference service<br/>[background.js]"]
  node_ui["Extension controls<br/>[ui.js]"]
  node_drop["Dropdown UI<br/>[drop.js]"]
  node_storage[("Extension storage")]
end

node_user(("WhatsApp user"))
node_wa["WhatsApp Web"]

node_user -->|"uses"| node_wa
node_wa -->|"exchanges frames"| node_ws
node_inject -->|"installs early"| node_ws
node_ws -->|"intercepts frames"| node_interception_logic
node_interception_logic -->|"decrypts frames"| node_multidevice
node_interception_logic -->|"decodes frames"| node_node_codec
node_interception_logic -->|"checks stanzas"| node_handler
node_handler -->|"blocks updates"| node_wa
node_handler -->|"fakes failure"| node_wa
node_background -->|"reads and writes"| node_storage
node_ui -->|"requests options"| node_background
node_ui -->|"creates menus"| node_drop
node_injected_ui -.->|"shows controls"| node_user
node_restore_ui -->|"restores messages"| node_user
node_status_download -->|"downloads statuses"| node_user
node_handler -->|"marks device origin"| node_user
node_binary_reader -.->|"supports decoding"| node_node_codec
node_binary_writer -.->|"supports encoding"| node_node_codec
node_proto_schema -.->|"describes messages"| node_multidevice
node_whisper_proto -.->|"describes messages"| node_multidevice
node_legacy_single -.->|"uses"| node_legacy_reader
node_legacy_single -.->|"uses"| node_legacy_writer

click node_ws "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ws_hook.js"
click node_inject "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core_injection.js"
click node_interception_logic "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/interception.js"
click node_handler "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/node_handler.js"
click node_multidevice "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/multi_device.js"
click node_binary_reader "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/binary_reader.js"
click node_binary_writer "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/binary_writer.js"
click node_node_codec "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/node_reader_writer.js"
click node_proto_schema "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/protobuf/WAProto.proto"
click node_whisper_proto "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/protobuf/WhisperTextProtocol.proto"
click node_legacy_single "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/legacy_single_device.js"
click node_legacy_reader "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/node_reader.js"
click node_legacy_writer "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/node_writer.js"
click node_restore_ui "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ui.js"
click node_injected_ui "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/injected_ui.js"
click node_status_download "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/status_download.js"
click node_compression "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/lib/pako.js"
click node_background "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/background.js"
click node_ui "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ui.js"
click node_drop "https://github.com/tomer8007/whatsapp-web-incognito/blob/master/lib/drop.js"

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_ws,node_inject,node_interception_logic,node_user toneBlue
class node_handler,node_multidevice,node_binary_reader,node_binary_writer,node_node_codec,node_proto_schema,node_whisper_proto,node_legacy_single,node_legacy_reader,node_legacy_writer,node_compression toneAmber
class node_restore_ui,node_injected_ui,node_status_download toneMint
class node_background,node_ui,node_drop,node_storage toneRose
class node_wa toneIndigo
```

## Components

### Traffic interception

- [WebSocket hook](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ws_hook.js): `core/ws_hook.js`
- [Page injection](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core_injection.js): `core_injection.js`
- [Frame interception](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/interception.js): `core/interception.js`

### Protocol handling

- [Node handling](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/node_handler.js): `core/node_handler.js`
- [Multi-device crypto](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/multi_device.js): `core/multi_device.js`
- [Binary reader](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/binary_reader.js): `core/parsing/binary_reader.js`
- [Binary writer](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/binary_writer.js): `core/parsing/binary_writer.js`
- [Node codec](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/node_reader_writer.js): `core/parsing/node_reader_writer.js`
- [Message schema](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/protobuf/WAProto.proto): `core/parsing/protobuf/WAProto.proto`
- [Whisper protocol](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/parsing/protobuf/WhisperTextProtocol.proto): `core/parsing/protobuf/WhisperTextProtocol.proto`
- [Legacy single-device](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/legacy_single_device.js): `old/legacy_single_device.js`
- [Legacy node reader](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/node_reader.js): `old/node_reader.js`
- [Legacy node writer](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/old/node_writer.js): `old/node_writer.js`
- [Compression utility](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/lib/pako.js): `lib/pako.js`

### User features

- [Message recovery UI](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ui.js): `core/ui.js`
- [Injected page UI](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/injected_ui.js): `core/injected_ui.js`
- [Status downloads](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/status_download.js): `core/status_download.js`

### Settings and UI

- [Preference service](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/background.js): `background.js`
- [Extension controls](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/core/ui.js): `core/ui.js`
- [Dropdown UI](https://github.com/tomer8007/whatsapp-web-incognito/blob/master/lib/drop.js): `lib/drop.js`
- **Extension storage**

### Other components

- **WhatsApp user**
- **WhatsApp Web**

## Connections

- WhatsApp user → WhatsApp Web: uses (evidence: `README.md`)
- WhatsApp Web → WebSocket hook: exchanges frames (evidence: `README.md`)
- Page injection → WebSocket hook: installs early (evidence: `core_injection.js`)
- WebSocket hook → Frame interception: intercepts frames (evidence: `README.md`)
- Frame interception → Multi-device crypto: decrypts frames (evidence: `README.md`)
- Frame interception → Node codec: decodes frames (evidence: `README.md`)
- Frame interception → Node handling: checks stanzas (evidence: `README.md`)
- Node handling → WhatsApp Web: blocks updates (evidence: `README.md`)
- Node handling → WhatsApp Web: fakes failure (evidence: `README.md`)
- Preference service → Extension storage: reads and writes (evidence: `background.js`)
- Extension controls → Preference service: requests options (evidence: `core/ui.js`)
- Extension controls → Dropdown UI: creates menus (evidence: `core/ui.js`)
- Injected page UI → WhatsApp user: shows controls
- Message recovery UI → WhatsApp user: restores messages (evidence: `README.md`)
- Status downloads → WhatsApp user: downloads statuses (evidence: `README.md`)
- Node handling → WhatsApp user: marks device origin (evidence: `README.md`)
- Binary reader → Node codec: supports decoding
- Binary writer → Node codec: supports encoding
- Message schema → Multi-device crypto: describes messages
- Whisper protocol → Multi-device crypto: describes messages
- Legacy single-device → Legacy node reader: uses
- Legacy single-device → Legacy node writer: uses
