# tgalal/yowsup architecture

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

- Interactive diagram: https://gitdiagram.com/tgalal/yowsup
- Repository: https://github.com/tgalal/yowsup

## Overview

Yowsup is a Python library for building WhatsApp clients. A client configures a profile, constructs a layered protocol stack, authenticates, and exchanges protocol traffic; separate registration requests handle account setup. The layers cover messaging and several social, media, and session features, with Axolotl providing encryption and profile-backed key state. Edges are limited to relationships shown by excerpts, SOURCE INDEX references, or the README; unsampled feature-layer internals are represented by their exact directories without inferred call chains.

Main entry points: [`yowsup/stacks/yowstack.py`](https://github.com/tgalal/yowsup/blob/master/yowsup/stacks/yowstack.py) (Layered Stack), [`yowsup/profile/profile.py`](https://github.com/tgalal/yowsup/blob/master/yowsup/profile/profile.py) (Client Profile), [`yowsup/layers/noise/layer.py`](https://github.com/tgalal/yowsup/blob/master/yowsup/layers/noise/layer.py) (Noise Handshake), [`yowsup/layers/coder`](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/coder) (Binary Codec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Profiles &amp; Registration"]
  node_profile["Client Profile<br/>[profile.py]"]
  node_config["Config Management<br/>[manager.py]"]
  node_registration["Account Registration"]
end

subgraph group_transport["Connection &amp; Encoding"]
  node_http["HTTP Requests<br/>[warequest.py]"]
  node_response["Response Parsing"]
  node_stack["Layered Stack<br/>[yowstack.py]"]
  node_auth["Authentication"]
  node_network["Network Transport<br/>[layer.py]"]
  node_noise["Noise Handshake<br/>[layer.py]"]
  node_coder["Binary Codec"]
  node_tree["Protocol Tree"]
end

subgraph group_features["WhatsApp Protocols"]
  node_messages["Messages"]
  node_media["Media Transfer"]
  node_contacts["Contacts Sync"]
  node_groups["Group Chats"]
  node_presence["Presence &amp; Chatstate"]
  node_otherprotocols["Other Protocols"]
end

subgraph group_security["Session Security"]
  node_crypto["Axolotl Manager<br/>[manager.py]"]
  node_keystore[("SQLite Key Store")]
end

node_client(("Client Application"))
node_wa(("WhatsApp Service"))

node_client -.->|"configures"| node_profile
node_profile -->|"loads and saves"| node_config
node_client -.->|"requests account setup"| node_registration
node_registration -->|"sends requests"| node_http
node_http -->|"parses responses"| node_response
node_profile -->|"creates manager"| node_crypto
node_stack -->|"constructs"| node_auth
node_stack -->|"constructs"| node_network
node_stack -->|"constructs"| node_noise
node_stack -->|"constructs"| node_coder
node_stack -->|"constructs"| node_messages
node_stack -->|"constructs"| node_media
node_stack -->|"constructs"| node_contacts
node_stack -->|"constructs"| node_groups
node_stack -->|"constructs"| node_presence
node_noise -->|"uses transport"| node_network
node_noise -->|"uses authentication"| node_auth
node_noise -->|"uses encoding"| node_coder
node_coder -.->|"encodes protocol nodes"| node_tree
node_profile -.->|"supports client communication"| node_wa
node_crypto -->|"uses persistent store"| node_keystore

click node_profile "https://github.com/tgalal/yowsup/blob/master/yowsup/profile/profile.py"
click node_config "https://github.com/tgalal/yowsup/blob/master/yowsup/config/manager.py"
click node_registration "https://github.com/tgalal/yowsup/tree/master/yowsup/registration"
click node_http "https://github.com/tgalal/yowsup/blob/master/yowsup/common/http/warequest.py"
click node_response "https://github.com/tgalal/yowsup/blob/master/yowsup/common/http/waresponseparser.py"
click node_stack "https://github.com/tgalal/yowsup/blob/master/yowsup/stacks/yowstack.py"
click node_auth "https://github.com/tgalal/yowsup/blob/master/yowsup/layers/auth/layer_authentication.py"
click node_network "https://github.com/tgalal/yowsup/blob/master/yowsup/layers/network/layer.py"
click node_noise "https://github.com/tgalal/yowsup/blob/master/yowsup/layers/noise/layer.py"
click node_coder "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/coder"
click node_tree "https://github.com/tgalal/yowsup/blob/master/yowsup/structs/protocoltreenode.py"
click node_messages "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_messages"
click node_media "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_media"
click node_contacts "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_contacts"
click node_groups "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_groups"
click node_presence "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_presence"
click node_otherprotocols "https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_iq"
click node_crypto "https://github.com/tgalal/yowsup/blob/master/yowsup/axolotl/manager.py"
click node_keystore "https://github.com/tgalal/yowsup/blob/master/yowsup/axolotl/store/sqlite/liteaxolotlstore.py"

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_profile,node_config,node_registration,node_client toneBlue
class node_http,node_response,node_stack,node_auth,node_network,node_noise,node_coder,node_tree toneAmber
class node_messages,node_media,node_contacts,node_groups,node_presence,node_otherprotocols toneMint
class node_crypto,node_keystore toneRose
class node_wa toneIndigo
```

## Components

### Profiles & Registration

- [Client Profile](https://github.com/tgalal/yowsup/blob/master/yowsup/profile/profile.py): `yowsup/profile/profile.py`
- [Config Management](https://github.com/tgalal/yowsup/blob/master/yowsup/config/manager.py): `yowsup/config/manager.py`
- [Account Registration](https://github.com/tgalal/yowsup/tree/master/yowsup/registration): `yowsup/registration`

### Connection & Encoding

- [HTTP Requests](https://github.com/tgalal/yowsup/blob/master/yowsup/common/http/warequest.py): `yowsup/common/http/warequest.py`
- [Response Parsing](https://github.com/tgalal/yowsup/blob/master/yowsup/common/http/waresponseparser.py): `yowsup/common/http/waresponseparser.py`
- [Layered Stack](https://github.com/tgalal/yowsup/blob/master/yowsup/stacks/yowstack.py): `yowsup/stacks/yowstack.py`
- [Authentication](https://github.com/tgalal/yowsup/blob/master/yowsup/layers/auth/layer_authentication.py): `yowsup/layers/auth/layer_authentication.py`
- [Network Transport](https://github.com/tgalal/yowsup/blob/master/yowsup/layers/network/layer.py): `yowsup/layers/network/layer.py`
- [Noise Handshake](https://github.com/tgalal/yowsup/blob/master/yowsup/layers/noise/layer.py): `yowsup/layers/noise/layer.py`
- [Binary Codec](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/coder): `yowsup/layers/coder`
- [Protocol Tree](https://github.com/tgalal/yowsup/blob/master/yowsup/structs/protocoltreenode.py): `yowsup/structs/protocoltreenode.py`

### WhatsApp Protocols

- [Messages](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_messages): `yowsup/layers/protocol_messages`
- [Media Transfer](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_media): `yowsup/layers/protocol_media`
- [Contacts Sync](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_contacts): `yowsup/layers/protocol_contacts`
- [Group Chats](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_groups): `yowsup/layers/protocol_groups`
- [Presence & Chatstate](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_presence): `yowsup/layers/protocol_presence`
- [Other Protocols](https://github.com/tgalal/yowsup/tree/master/yowsup/layers/protocol_iq): `yowsup/layers/protocol_iq`

### Session Security

- [Axolotl Manager](https://github.com/tgalal/yowsup/blob/master/yowsup/axolotl/manager.py): `yowsup/axolotl/manager.py`
- [SQLite Key Store](https://github.com/tgalal/yowsup/blob/master/yowsup/axolotl/store/sqlite/liteaxolotlstore.py): `yowsup/axolotl/store/sqlite/liteaxolotlstore.py`

### Other components

- **Client Application**
- **WhatsApp Service**

## Connections

- Client Application → Client Profile: configures
- Client Profile → Config Management: loads and saves (evidence: `yowsup/profile/profile.py`)
- Client Application → Account Registration: requests account setup
- Account Registration → HTTP Requests: sends requests (evidence: `yowsup/registration/coderequest.py`)
- HTTP Requests → Response Parsing: parses responses (evidence: `yowsup/common/http/warequest.py`)
- Client Profile → Axolotl Manager: creates manager (evidence: `yowsup/profile/profile.py`)
- Layered Stack → Authentication: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Network Transport: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Noise Handshake: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Binary Codec: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Messages: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Media Transfer: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Contacts Sync: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Group Chats: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Layered Stack → Presence & Chatstate: constructs (evidence: `yowsup/stacks/yowstack.py`)
- Noise Handshake → Network Transport: uses transport (evidence: `yowsup/layers/noise/layer.py`)
- Noise Handshake → Authentication: uses authentication (evidence: `yowsup/layers/noise/layer.py`)
- Noise Handshake → Binary Codec: uses encoding (evidence: `yowsup/layers/noise/layer.py`)
- Binary Codec → Protocol Tree: encodes protocol nodes
- Client Profile → WhatsApp Service: supports client communication
- Axolotl Manager → SQLite Key Store: uses persistent store (evidence: `yowsup/axolotl/manager.py`)
