# jfcodes/whatsappjs architecture

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

- Interactive diagram: https://gitdiagram.com/jfcodes/whatsappjs
- Repository: https://github.com/jfcodes/whatsappjs

## Overview

WhatsAppJS is a WhatsApp Web automation wrapper, currently marked v2 WIP. Its main workflow launches a Puppeteer browser, navigates to WhatsApp Web, detects login and exposes a QR code, then focuses a configured chat, reads incoming messages, dispatches app commands, and sends replies. The crypto app is a documented-in-code capability that fetches Binance average prices. Edges reflect calls visible in sampled source or the README; unsampled utility and evaluator internals are not expanded beyond the relationships evidenced by their caller.

Main entry points: [`src/whastapp/instance.ts`](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/instance.ts) (WhatsApp controller), [`src/whastapp/_selectors.ts`](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/_selectors.ts) (Page selectors), [`src/APPS/crypto/app.ts`](https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/crypto/app.ts) (Crypto commands), [`src/bot/instance.ts`](https://github.com/jfcodes/whatsappjs/blob/master/src/bot/instance.ts) (Puppeteer browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Automation runtime"]
  node_entry["Runtime entry<br/>[index.ts]"]
  node_controller["WhatsApp controller<br/>[instance.ts]"]
  node_browser["Puppeteer browser<br/>[instance.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
  node_qrfile["QR image file"]
end

subgraph group_whatsapp["WhatsApp interaction"]
  node_login["Login detection<br/>[isLoginPage.ts]"]
  node_qr["QR extraction<br/>[extrackQrCode.ts]"]
  node_selectors["Page selectors<br/>[_selectors.ts]"]
  node_chatfocus["Chat selection<br/>[focusChat.ts]"]
  node_incoming["Incoming message scan<br/>[lastInput.ts]"]
  node_messageextract["Message extraction<br/>[extractMessage.ts]"]
  node_send["Message sending<br/>[sendMessage.ts]"]
end

subgraph group_commands["Command apps"]
  node_appregistry["App contract<br/>[_app.ts]"]
  node_crypto["Crypto commands<br/>[app.ts]"]
  node_format["Price formatting<br/>[formatMoney.ts]"]
end

node_operator(("Operator"))
node_web["WhatsApp Web"]
node_binance["Binance price API"]

node_operator -->|"starts"| node_entry
node_entry -->|"creates"| node_controller
node_controller -->|"initializes"| node_browser
node_controller -->|"reads settings"| node_config
node_browser -->|"reads settings"| node_config
node_controller -->|"navigates"| node_browser
node_browser -->|"controls page"| node_web
node_controller -->|"checks login"| node_login
node_login -->|"queries selectors"| node_selectors
node_controller -->|"extracts QR"| node_qr
node_qr -->|"queries selectors"| node_selectors
node_controller -->|"saves QR image"| node_qrfile
node_controller -->|"focuses chat"| node_chatfocus
node_chatfocus -->|"uses selectors"| node_selectors
node_controller -->|"sends messages"| node_send
node_send -->|"uses selectors"| node_selectors
node_controller -->|"polls messages"| node_incoming
node_controller -->|"extracts message"| node_messageextract
node_messageextract -->|"uses selectors"| node_selectors
node_controller -->|"registers apps"| node_appregistry
node_controller -->|"installs and dispatches"| node_crypto
node_crypto -->|"extends contract"| node_appregistry
node_crypto -->|"requests price"| node_binance
node_crypto -->|"formats price"| node_format

click node_entry "https://github.com/jfcodes/whatsappjs/blob/master/src/index.ts"
click node_controller "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/instance.ts"
click node_browser "https://github.com/jfcodes/whatsappjs/blob/master/src/bot/instance.ts"
click node_config "https://github.com/jfcodes/whatsappjs/blob/master/src/config.ts"
click node_login "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/isLoginPage.ts"
click node_qr "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/extrackQrCode.ts"
click node_selectors "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/_selectors.ts"
click node_chatfocus "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/actions/focusChat.ts"
click node_incoming "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/lastInput.ts"
click node_messageextract "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/extractMessage.ts"
click node_send "https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/actions/sendMessage.ts"
click node_appregistry "https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/_app.ts"
click node_crypto "https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/crypto/app.ts"
click node_format "https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/crypto/utils/formatMoney.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_entry,node_controller,node_browser,node_config,node_qrfile toneBlue
class node_login,node_qr,node_selectors,node_chatfocus,node_incoming,node_messageextract,node_send toneAmber
class node_appregistry,node_crypto,node_format,node_binance toneMint
class node_operator,node_web toneIndigo
```

## Components

### Automation runtime

- [Runtime entry](https://github.com/jfcodes/whatsappjs/blob/master/src/index.ts): `src/index.ts`
- [WhatsApp controller](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/instance.ts): `src/whastapp/instance.ts`
- [Puppeteer browser](https://github.com/jfcodes/whatsappjs/blob/master/src/bot/instance.ts): `src/bot/instance.ts`
- [Runtime config](https://github.com/jfcodes/whatsappjs/blob/master/src/config.ts): `src/config.ts`
- **QR image file**

### WhatsApp interaction

- [Login detection](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/isLoginPage.ts): `src/whastapp/evaluators/isLoginPage.ts`
- [QR extraction](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/extrackQrCode.ts): `src/whastapp/evaluators/extrackQrCode.ts`
- [Page selectors](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/_selectors.ts): `src/whastapp/_selectors.ts`
- [Chat selection](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/actions/focusChat.ts): `src/whastapp/actions/focusChat.ts`
- [Incoming message scan](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/lastInput.ts): `src/whastapp/evaluators/lastInput.ts`
- [Message extraction](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/evaluators/extractMessage.ts): `src/whastapp/evaluators/extractMessage.ts`
- [Message sending](https://github.com/jfcodes/whatsappjs/blob/master/src/whastapp/actions/sendMessage.ts): `src/whastapp/actions/sendMessage.ts`

### Command apps

- [App contract](https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/_app.ts): `src/APPS/_app.ts`
- [Crypto commands](https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/crypto/app.ts): `src/APPS/crypto/app.ts`
- [Price formatting](https://github.com/jfcodes/whatsappjs/blob/master/src/APPS/crypto/utils/formatMoney.ts): `src/APPS/crypto/utils/formatMoney.ts`

### Other components

- **Operator**
- **WhatsApp Web**
- **Binance price API**

## Connections

- Operator → Runtime entry: starts
- Runtime entry → WhatsApp controller: creates (evidence: `src/index.ts`)
- WhatsApp controller → Puppeteer browser: initializes (evidence: `src/whastapp/instance.ts`)
- WhatsApp controller → Runtime config: reads settings (evidence: `src/whastapp/instance.ts`)
- Puppeteer browser → Runtime config: reads settings (evidence: `src/bot/instance.ts`)
- WhatsApp controller → Puppeteer browser: navigates (evidence: `src/whastapp/instance.ts`)
- Puppeteer browser → WhatsApp Web: controls page (evidence: `src/bot/instance.ts`)
- WhatsApp controller → Login detection: checks login (evidence: `src/whastapp/instance.ts`)
- Login detection → Page selectors: queries selectors (evidence: `src/whastapp/evaluators/isLoginPage.ts`)
- WhatsApp controller → QR extraction: extracts QR (evidence: `src/whastapp/instance.ts`)
- QR extraction → Page selectors: queries selectors (evidence: `src/whastapp/evaluators/extrackQrCode.ts`)
- WhatsApp controller → QR image file: saves QR image (evidence: `src/whastapp/instance.ts`)
- WhatsApp controller → Chat selection: focuses chat (evidence: `src/whastapp/instance.ts`)
- Chat selection → Page selectors: uses selectors (evidence: `src/whastapp/actions/focusChat.ts`)
- WhatsApp controller → Message sending: sends messages (evidence: `src/whastapp/instance.ts`)
- Message sending → Page selectors: uses selectors (evidence: `src/whastapp/actions/sendMessage.ts`)
- WhatsApp controller → Incoming message scan: polls messages (evidence: `src/whastapp/instance.ts`)
- WhatsApp controller → Message extraction: extracts message (evidence: `src/whastapp/instance.ts`)
- Message extraction → Page selectors: uses selectors (evidence: `src/whastapp/evaluators/extractMessage.ts`)
- WhatsApp controller → App contract: registers apps (evidence: `src/whastapp/instance.ts`)
- WhatsApp controller → Crypto commands: installs and dispatches (evidence: `src/whastapp/instance.ts`)
- Crypto commands → App contract: extends contract (evidence: `src/APPS/crypto/app.ts`)
- Crypto commands → Binance price API: requests price (evidence: `src/APPS/crypto/app.ts`)
- Crypto commands → Price formatting: formats price (evidence: `src/APPS/crypto/app.ts`)
