# giacomoferretti/whatsapp-backup-downloader-decryptor architecture

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

- Interactive diagram: https://gitdiagram.com/giacomoferretti/whatsapp-backup-downloader-decryptor
- Repository: https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor

## Overview

wabdd is a command-line tool for obtaining Google Drive credentials, downloading WhatsApp end-to-end encrypted backups, and decrypting supported backup files. The user workflow is token creation, backup selection and download, then local decryption with a 64-digit key; downloading and decrypting are separate commands. The graph also shows the Google Drive API client and shared utilities. Source excerpts establish the command routing, authentication, backup listing, file processing, and decryption behavior; some download-worker details are omitted, so uncertain links are not inferred.

Main entry points: [`wabdd/commands/download.py`](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/download.py) (Download command), [`wabdd/commands/token.py`](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/token.py) (Token command), [`wabdd/wabackup.py`](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/wabackup.py) (Drive client), [`wabdd/commands/decrypt.py`](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/decrypt.py) (Decrypt command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_commands["Command router<br/>[__main__.py]"]
  node_utils["Shared utilities<br/>[utils.py]"]
  node_constants["Runtime constants<br/>[constants.py]"]
end

subgraph group_auth["Authentication"]
  node_token["Token command<br/>[token.py]"]
  node_authhelper["Auth helper<br/>[gpsoauth_helper.py]"]
  node_tokenfiles["Token files"]
  node_googleauth{{"Google auth"}}
end

subgraph group_download["Backup download"]
  node_downloadcmd["Download command<br/>[download.py]"]
  node_client["Drive client<br/>[wabackup.py]"]
  node_driveapi{{"Google Drive API"}}
  node_backupfiles["Backup files"]
  node_localdump["Local backup"]
end

subgraph group_decrypt["Decryption"]
  node_decryptcmd["Decrypt command<br/>[decrypt.py]"]
  node_crypto{{"Crypt tools"}}
  node_decrypted["Decrypted files"]
end

node_user(("User"))

node_user -->|"runs commands"| node_commands
node_commands -->|"routes token"| node_token
node_commands -->|"routes download"| node_downloadcmd
node_commands -->|"routes decrypt"| node_decryptcmd
node_user -->|"provides cookie"| node_token
node_token -->|"exchanges credentials"| node_googleauth
node_token -->|"requests auth token"| node_authhelper
node_authhelper -->|"requests Drive token"| node_googleauth
node_token -->|"writes tokens"| node_tokenfiles
node_user -->|"starts download"| node_downloadcmd
node_downloadcmd -->|"lists backup files"| node_client
node_downloadcmd -->|"collects file metadata"| node_backupfiles
node_client -->|"requests backup data"| node_driveapi
node_driveapi -.->|"serves backup data"| node_backupfiles
node_downloadcmd -->|"writes downloads"| node_localdump
node_user -->|"provides key and dump"| node_decryptcmd
node_decryptcmd -->|"decrypts files"| node_crypto
node_decryptcmd -->|"reads backup"| node_localdump
node_decryptcmd -->|"writes results"| node_decrypted
node_downloadcmd -->|"uses helpers"| node_utils
node_downloadcmd -->|"uses settings"| node_constants
node_token -->|"generates ID"| node_utils
node_client -->|"refreshes credentials"| node_authhelper
node_client -->|"generates ID"| node_utils
node_client -->|"sets user agent"| node_constants

click node_commands "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/__main__.py"
click node_token "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/token.py"
click node_authhelper "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/gpsoauth_helper.py"
click node_downloadcmd "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/download.py"
click node_client "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/wabackup.py"
click node_decryptcmd "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/decrypt.py"
click node_utils "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/utils.py"
click node_constants "https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/constants.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_commands,node_utils,node_constants,node_user toneBlue
class node_token,node_authhelper,node_tokenfiles,node_googleauth toneAmber
class node_downloadcmd,node_client,node_driveapi,node_backupfiles,node_localdump toneMint
class node_decryptcmd,node_crypto,node_decrypted toneRose
```

## Components

### CLI

- [Command router](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/__main__.py): `wabdd/__main__.py`
- [Shared utilities](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/utils.py): `wabdd/utils.py`
- [Runtime constants](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/constants.py): `wabdd/constants.py`

### Authentication

- [Token command](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/token.py): `wabdd/commands/token.py`
- [Auth helper](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/gpsoauth_helper.py): `wabdd/gpsoauth_helper.py`
- **Token files**
- **Google auth**

### Backup download

- [Download command](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/download.py): `wabdd/commands/download.py`
- [Drive client](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/wabackup.py): `wabdd/wabackup.py`
- **Google Drive API**
- **Backup files**
- **Local backup**

### Decryption

- [Decrypt command](https://github.com/giacomoferretti/whatsapp-backup-downloader-decryptor/blob/main/wabdd/commands/decrypt.py): `wabdd/commands/decrypt.py`
- **Crypt tools**
- **Decrypted files**

### Other components

- **User**

## Connections

- User → Command router: runs commands (evidence: `README.md`)
- Command router → Token command: routes token (evidence: `wabdd/__main__.py`)
- Command router → Download command: routes download (evidence: `wabdd/__main__.py`)
- Command router → Decrypt command: routes decrypt (evidence: `wabdd/__main__.py`)
- User → Token command: provides cookie (evidence: `wabdd/commands/token.py`)
- Token command → Google auth: exchanges credentials (evidence: `wabdd/commands/token.py`)
- Token command → Auth helper: requests auth token (evidence: `wabdd/commands/token.py`)
- Auth helper → Google auth: requests Drive token (evidence: `wabdd/gpsoauth_helper.py`)
- Token command → Token files: writes tokens (evidence: `wabdd/commands/token.py`)
- User → Download command: starts download (evidence: `README.md`)
- Download command → Drive client: lists backup files (evidence: `wabdd/commands/download.py`)
- Download command → Backup files: collects file metadata (evidence: `wabdd/commands/download.py`)
- Drive client → Google Drive API: requests backup data (evidence: `wabdd/wabackup.py`)
- Google Drive API → Backup files: serves backup data
- Download command → Local backup: writes downloads (evidence: `README.md`)
- User → Decrypt command: provides key and dump (evidence: `README.md`)
- Decrypt command → Crypt tools: decrypts files (evidence: `wabdd/commands/decrypt.py`)
- Decrypt command → Local backup: reads backup (evidence: `wabdd/commands/decrypt.py`)
- Decrypt command → Decrypted files: writes results (evidence: `wabdd/commands/decrypt.py`)
- Download command → Shared utilities: uses helpers (evidence: `wabdd/commands/download.py`)
- Download command → Runtime constants: uses settings (evidence: `wabdd/commands/download.py`)
- Token command → Shared utilities: generates ID (evidence: `wabdd/commands/token.py`)
- Drive client → Auth helper: refreshes credentials (evidence: `wabdd/wabackup.py`)
- Drive client → Shared utilities: generates ID (evidence: `wabdd/wabackup.py`)
- Drive client → Runtime constants: sets user agent (evidence: `wabdd/wabackup.py`)
