# whiskeysockets/baileys architecture

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

- Interactive diagram: https://gitdiagram.com/whiskeysockets/baileys
- Repository: https://github.com/whiskeysockets/baileys

## Overview

Baileys is a TypeScript WebSocket client library for interacting with WhatsApp Web. A user supplies authentication and socket configuration; the library establishes a connection, exchanges binary protocol frames, and exposes socket operations for sending and receiving messages and managing chats and groups. The runtime also includes Signal encryption, authentication state, media and message processing, contact synchronization, and business/newsletter features. Several socket implementations are present in the tree but were not sampled, so links involving those modules are omitted or marked unverified rather than inferred.

Main entry points: [`src/Socket/socket.ts`](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/socket.ts) (Socket orchestration), [`src/Socket/messages-send.ts`](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-send.ts) (Message sending), [`src/Socket/messages-recv.ts`](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-recv.ts) (Message receiving), [`src/Signal/libsignal.ts`](https://github.com/whiskeysockets/baileys/blob/master/src/Signal/libsignal.ts) (Signal repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection and protocol"]
  node_public_api["Public API<br/>[index.ts]"]
  node_socket_core["Socket orchestration<br/>[socket.ts]"]
  node_websocket["WebSocket transport<br/>[websocket.ts]"]
  node_noise["Noise handshake<br/>[noise-handler.ts]"]
  node_binary["Binary codec<br/>[decode.ts]"]
end

subgraph group_messaging["Messaging and chats"]
  node_send["Message sending<br/>[messages-send.ts]"]
  node_receive["Message receiving<br/>[messages-recv.ts]"]
  node_chat_ops["Chat operations<br/>[chats.ts]"]
  node_group_ops["Group operations<br/>[groups.ts]"]
  node_community_ops["Community operations<br/>[communities.ts]"]
  node_business_ops["Business operations<br/>[business.ts]"]
  node_newsletter_ops["Newsletter operations<br/>[newsletter.ts]"]
  node_message_utils["Message processing<br/>[process-message.ts]"]
  node_media_utils["Media handling<br/>[messages-media.ts]"]
end

subgraph group_security["Identity and security"]
  node_signal_repo["Signal repository<br/>[libsignal.ts]"]
  node_group_cipher["Group encryption<br/>[group_cipher.ts]"]
  node_lid_mapping["LID mapping<br/>[lid-mapping.ts]"]
  node_auth_state[("Authentication state")]
end

subgraph group_support["Sync and shared services"]
  node_defaults["Runtime defaults<br/>[index.ts]"]
  node_usync["Contact synchronization<br/>[USyncQuery.ts]"]
  node_usync_protocols["Sync protocols"]
  node_retry["Retry management"]
  node_types_message["Message model<br/>[Message.ts]"]
  node_types_group["Group metadata model<br/>[GroupMetadata.ts]"]
  node_chat_utils["Chat utilities<br/>[chat-utils.ts]"]
  node_crypto_utils["Cryptography<br/>[crypto.ts]"]
  node_link_preview["Link previews<br/>[link-preview.ts]"]
  node_tc_tokens["Token utilities<br/>[tc-token-utils.ts]"]
  node_logger["Logging<br/>[logger.ts]"]
  node_generics["Shared utilities<br/>[generics.ts]"]
  node_jid_utils["JID utilities<br/>[jid-utils.ts]"]
end

node_user(("Library user"))
node_wa(("WhatsApp Web"))

node_user -->|"uses"| node_public_api
node_public_api -->|"exports"| node_socket_core
node_socket_core -.->|"dispatches"| node_websocket
node_websocket -.->|"connects"| node_wa
node_noise -->|"decodes frames"| node_binary
node_noise -->|"encrypts frames"| node_crypto_utils
node_socket_core -.->|"dispatches"| node_send
node_socket_core -.->|"dispatches"| node_receive
node_receive -->|"parses nodes"| node_binary
node_send -->|"encodes nodes"| node_binary
node_send -->|"encrypts messages"| node_signal_repo
node_send -->|"gets previews"| node_link_preview
node_send -->|"stores tokens"| node_tc_tokens
node_receive -->|"sends retries"| node_send
node_receive -->|"checks retries"| node_retry
node_receive -->|"reads tokens"| node_tc_tokens
node_receive -.->|"processes messages"| node_message_utils
node_send -.->|"handles media"| node_media_utils
node_signal_repo -->|"uses"| node_group_cipher
node_signal_repo -->|"uses"| node_lid_mapping
node_defaults -->|"configures"| node_signal_repo
node_usync -->|"parses with"| node_usync_protocols
node_usync -->|"parses nodes"| node_binary
node_send -->|"queries"| node_usync
node_socket_core -.->|"exposes"| node_chat_ops
node_socket_core -.->|"exposes"| node_group_ops
node_socket_core -.->|"exposes"| node_community_ops
node_socket_core -.->|"exposes"| node_business_ops
node_socket_core -.->|"exposes"| node_newsletter_ops
node_socket_core -.->|"uses"| node_auth_state
node_chat_utils -->|"imports"| node_generics
node_signal_repo -->|"uses"| node_generics
node_receive -->|"uses types"| node_types_message
node_chat_ops -.->|"uses types"| node_types_group
node_noise -->|"reads settings"| node_defaults

click node_public_api "https://github.com/whiskeysockets/baileys/blob/master/src/index.ts"
click node_socket_core "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/socket.ts"
click node_websocket "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/Client/websocket.ts"
click node_noise "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/noise-handler.ts"
click node_binary "https://github.com/whiskeysockets/baileys/blob/master/src/WABinary/decode.ts"
click node_send "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-send.ts"
click node_receive "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-recv.ts"
click node_chat_ops "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/chats.ts"
click node_group_ops "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/groups.ts"
click node_community_ops "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/communities.ts"
click node_business_ops "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/business.ts"
click node_newsletter_ops "https://github.com/whiskeysockets/baileys/blob/master/src/Socket/newsletter.ts"
click node_message_utils "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/process-message.ts"
click node_media_utils "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/messages-media.ts"
click node_signal_repo "https://github.com/whiskeysockets/baileys/blob/master/src/Signal/libsignal.ts"
click node_group_cipher "https://github.com/whiskeysockets/baileys/blob/master/src/Signal/Group/group_cipher.ts"
click node_lid_mapping "https://github.com/whiskeysockets/baileys/blob/master/src/Signal/lid-mapping.ts"
click node_auth_state "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/use-multi-file-auth-state.ts"
click node_defaults "https://github.com/whiskeysockets/baileys/blob/master/src/Defaults/index.ts"
click node_usync "https://github.com/whiskeysockets/baileys/blob/master/src/WAUSync/USyncQuery.ts"
click node_usync_protocols "https://github.com/whiskeysockets/baileys/blob/master/src/WAUSync/Protocols/USyncContactProtocol.ts"
click node_retry "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/message-retry-manager.ts"
click node_types_message "https://github.com/whiskeysockets/baileys/blob/master/src/Types/Message.ts"
click node_types_group "https://github.com/whiskeysockets/baileys/blob/master/src/Types/GroupMetadata.ts"
click node_chat_utils "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/chat-utils.ts"
click node_crypto_utils "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/crypto.ts"
click node_link_preview "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/link-preview.ts"
click node_tc_tokens "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/tc-token-utils.ts"
click node_logger "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/logger.ts"
click node_generics "https://github.com/whiskeysockets/baileys/blob/master/src/Utils/generics.ts"
click node_jid_utils "https://github.com/whiskeysockets/baileys/blob/master/src/WABinary/jid-utils.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_public_api,node_socket_core,node_websocket,node_noise,node_binary,node_user toneBlue
class node_send,node_receive,node_chat_ops,node_group_ops,node_community_ops,node_business_ops,node_newsletter_ops,node_message_utils,node_media_utils toneAmber
class node_signal_repo,node_group_cipher,node_lid_mapping,node_auth_state toneMint
class node_defaults,node_usync,node_usync_protocols,node_retry,node_types_message,node_types_group,node_chat_utils,node_crypto_utils,node_link_preview,node_tc_tokens,node_logger,node_generics,node_jid_utils toneRose
class node_wa toneIndigo
```

## Components

### Connection and protocol

- [Public API](https://github.com/whiskeysockets/baileys/blob/master/src/index.ts): `src/index.ts`
- [Socket orchestration](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/socket.ts): `src/Socket/socket.ts`
- [WebSocket transport](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/Client/websocket.ts): `src/Socket/Client/websocket.ts`
- [Noise handshake](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/noise-handler.ts): `src/Utils/noise-handler.ts`
- [Binary codec](https://github.com/whiskeysockets/baileys/blob/master/src/WABinary/decode.ts): `src/WABinary/decode.ts`

### Messaging and chats

- [Message sending](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-send.ts): `src/Socket/messages-send.ts`
- [Message receiving](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/messages-recv.ts): `src/Socket/messages-recv.ts`
- [Chat operations](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/chats.ts): `src/Socket/chats.ts`
- [Group operations](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/groups.ts): `src/Socket/groups.ts`
- [Community operations](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/communities.ts): `src/Socket/communities.ts`
- [Business operations](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/business.ts): `src/Socket/business.ts`
- [Newsletter operations](https://github.com/whiskeysockets/baileys/blob/master/src/Socket/newsletter.ts): `src/Socket/newsletter.ts`
- [Message processing](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/process-message.ts): `src/Utils/process-message.ts`
- [Media handling](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/messages-media.ts): `src/Utils/messages-media.ts`

### Identity and security

- [Signal repository](https://github.com/whiskeysockets/baileys/blob/master/src/Signal/libsignal.ts): `src/Signal/libsignal.ts`
- [Group encryption](https://github.com/whiskeysockets/baileys/blob/master/src/Signal/Group/group_cipher.ts): `src/Signal/Group/group_cipher.ts`
- [LID mapping](https://github.com/whiskeysockets/baileys/blob/master/src/Signal/lid-mapping.ts): `src/Signal/lid-mapping.ts`
- [Authentication state](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/use-multi-file-auth-state.ts): `src/Utils/use-multi-file-auth-state.ts`

### Sync and shared services

- [Runtime defaults](https://github.com/whiskeysockets/baileys/blob/master/src/Defaults/index.ts): `src/Defaults/index.ts`
- [Contact synchronization](https://github.com/whiskeysockets/baileys/blob/master/src/WAUSync/USyncQuery.ts): `src/WAUSync/USyncQuery.ts`
- [Sync protocols](https://github.com/whiskeysockets/baileys/blob/master/src/WAUSync/Protocols/USyncContactProtocol.ts): `src/WAUSync/Protocols/USyncContactProtocol.ts`
- [Retry management](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/message-retry-manager.ts): `src/Utils/message-retry-manager.ts`
- [Message model](https://github.com/whiskeysockets/baileys/blob/master/src/Types/Message.ts): `src/Types/Message.ts`
- [Group metadata model](https://github.com/whiskeysockets/baileys/blob/master/src/Types/GroupMetadata.ts): `src/Types/GroupMetadata.ts`
- [Chat utilities](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/chat-utils.ts): `src/Utils/chat-utils.ts`
- [Cryptography](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/crypto.ts): `src/Utils/crypto.ts`
- [Link previews](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/link-preview.ts): `src/Utils/link-preview.ts`
- [Token utilities](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/tc-token-utils.ts): `src/Utils/tc-token-utils.ts`
- [Logging](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/logger.ts): `src/Utils/logger.ts`
- [Shared utilities](https://github.com/whiskeysockets/baileys/blob/master/src/Utils/generics.ts): `src/Utils/generics.ts`
- [JID utilities](https://github.com/whiskeysockets/baileys/blob/master/src/WABinary/jid-utils.ts): `src/WABinary/jid-utils.ts`

### Other components

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

## Connections

- Library user → Public API: uses (evidence: `README.md`)
- Public API → Socket orchestration: exports (evidence: `src/index.ts`)
- Socket orchestration → WebSocket transport: dispatches
- WebSocket transport → WhatsApp Web: connects
- Noise handshake → Binary codec: decodes frames (evidence: `src/Utils/noise-handler.ts`)
- Noise handshake → Cryptography: encrypts frames (evidence: `src/Utils/noise-handler.ts`)
- Socket orchestration → Message sending: dispatches
- Socket orchestration → Message receiving: dispatches
- Message receiving → Binary codec: parses nodes (evidence: `src/Socket/messages-recv.ts`)
- Message sending → Binary codec: encodes nodes (evidence: `src/Socket/messages-send.ts`)
- Message sending → Signal repository: encrypts messages (evidence: `src/Socket/messages-send.ts`)
- Message sending → Link previews: gets previews (evidence: `src/Socket/messages-send.ts`)
- Message sending → Token utilities: stores tokens (evidence: `src/Socket/messages-send.ts`)
- Message receiving → Message sending: sends retries (evidence: `src/Socket/messages-recv.ts`)
- Message receiving → Retry management: checks retries (evidence: `src/Socket/messages-recv.ts`)
- Message receiving → Token utilities: reads tokens (evidence: `src/Socket/messages-recv.ts`)
- Message receiving → Message processing: processes messages
- Message sending → Media handling: handles media
- Signal repository → Group encryption: uses (evidence: `src/Signal/libsignal.ts`)
- Signal repository → LID mapping: uses (evidence: `src/Signal/libsignal.ts`)
- Runtime defaults → Signal repository: configures (evidence: `src/Defaults/index.ts`)
- Contact synchronization → Sync protocols: parses with (evidence: `src/WAUSync/USyncQuery.ts`)
- Contact synchronization → Binary codec: parses nodes (evidence: `src/WAUSync/USyncQuery.ts`)
- Message sending → Contact synchronization: queries (evidence: `src/Socket/messages-send.ts`)
- Socket orchestration → Chat operations: exposes
- Socket orchestration → Group operations: exposes
- Socket orchestration → Community operations: exposes
- Socket orchestration → Business operations: exposes
- Socket orchestration → Newsletter operations: exposes
- Socket orchestration → Authentication state: uses
- Chat utilities → Shared utilities: imports (evidence: `src/Utils/index.ts`)
- Signal repository → Shared utilities: uses
- Message receiving → Message model: uses types (evidence: `src/Types/Message.ts`)
- Chat operations → Group metadata model: uses types
- Noise handshake → Runtime defaults: reads settings (evidence: `src/Utils/noise-handler.ts`)
