# gabrielfranicevich/wpp architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielfranicevich/wpp
- Repository: https://github.com/gabrielfranicevich/wpp

## Overview

wpp is a terminal WhatsApp client. Its main workflow loads the active saved session, resolves a chat, then lists or pages through conversations and sends messages through an application-facing WhatsApp abstraction backed by the native client. Other branches cover login and session management, chat search and management, realtime listening, and message synchronization into a separate SQLite cache. The README documents the major layers and storage split; several implementation details are not sampled, so their links are included only where the README or SOURCE INDEX supports them.

Main entry points: [`src/cli/mod.rs`](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/mod.rs) (Command router), [`src/whatsapp/client.rs`](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/client.rs) (WhatsApp abstraction), [`src/cli/chat.rs`](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/chat.rs) (Chat command), [`src/terminal/pager.rs`](https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/pager.rs) (Interactive pager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["CLI commands"]
  node_main["Application entry<br/>[main.rs]"]
  node_cli["Command router<br/>[mod.rs]"]
  node_login["Login<br/>[login.rs]"]
  node_sessions["Session commands<br/>[session.rs]"]
  node_switch["Switch session<br/>[switch.rs]"]
  node_logout["Logout<br/>[logout.rs]"]
  node_chatcmd["Chat command<br/>[chat.rs]"]
  node_listcmd["List and search<br/>[list.rs]"]
  node_sendcmd["Send command<br/>[send.rs]"]
  node_synccmd["Sync command<br/>[sync.rs]"]
  node_listen["Realtime listen<br/>[listen.rs]"]
end

subgraph group_application["Application services"]
  node_resolver["Chat resolution<br/>[chat_resolver.rs]"]
  node_listing["Chat listing<br/>[chat_listing.rs]"]
  node_chatops["Chat management<br/>[chats.rs]"]
  node_messagepager["Message history<br/>[message_pager.rs]"]
  node_messages["Message sending<br/>[messages.rs]"]
  node_syncservice["Message sync<br/>[sync.rs]"]
end

subgraph group_terminal["Terminal interface"]
  node_terminalpager["Interactive pager<br/>[pager.rs]"]
  node_composer["Message composer<br/>[composer.rs]"]
  node_render["Terminal rendering<br/>[render.rs]"]
end

subgraph group_whatsapp["WhatsApp connectivity"]
  node_abstraction["WhatsApp abstraction<br/>[client.rs]"]
  node_models["Domain models<br/>[models.rs]"]
  node_nativeclient["Native client<br/>[client.rs]"]
  node_auth["Native authentication<br/>[auth.rs]"]
  node_nativechats["Native chat operations<br/>[chats.rs]"]
  node_nativemessages["Native messaging<br/>[messages.rs]"]
  node_realtime["Realtime events<br/>[realtime.rs]"]
end

subgraph group_state["Session and cache"]
  node_context["Active app context<br/>[state.rs]"]
  node_config["Session configuration<br/>[config.rs]"]
  node_cache[("SQLite message cache<br/>[sqlite.rs]")]
end

node_user(("Terminal user"))
node_whatsappservice(("WhatsApp service"))

node_user -->|"runs"| node_main
node_main -->|"dispatches"| node_cli
node_cli -->|"routes login"| node_login
node_cli -->|"routes session"| node_sessions
node_cli -->|"routes switch"| node_switch
node_cli -->|"routes logout"| node_logout
node_cli -->|"routes chat"| node_chatcmd
node_cli -->|"routes list"| node_listcmd
node_cli -->|"routes send"| node_sendcmd
node_cli -->|"routes sync"| node_synccmd
node_cli -->|"routes listen"| node_listen
node_login -->|"authenticates"| node_auth
node_login -->|"saves session"| node_config
node_switch -->|"selects session"| node_config
node_logout -->|"removes metadata"| node_config
node_context -->|"loads active session"| node_config
node_context -->|"opens client"| node_abstraction
node_chatcmd -->|"resolves target"| node_resolver
node_chatcmd -->|"manages chat"| node_chatops
node_chatcmd -->|"loads history"| node_messagepager
node_chatcmd -->|"opens pager"| node_terminalpager
node_listcmd -->|"lists chats"| node_listing
node_listcmd -->|"renders results"| node_render
node_sendcmd -->|"resolves target"| node_resolver
node_sendcmd -->|"sends text"| node_messages
node_synccmd -->|"starts sync"| node_syncservice
node_syncservice -->|"writes cache"| node_cache
node_listen -->|"opens listener"| node_abstraction
node_terminalpager -->|"uses composer"| node_composer
node_terminalpager -->|"pages history"| node_messagepager
node_terminalpager -->|"receives events"| node_abstraction
node_resolver -->|"queries chats"| node_abstraction
node_listing -->|"lists chats"| node_abstraction
node_chatops -->|"manages chats"| node_abstraction
node_messagepager -->|"loads messages"| node_abstraction
node_messagepager -->|"delegates sending"| node_messages
node_messages -->|"sends text"| node_abstraction
node_syncservice -->|"fetches messages"| node_abstraction
node_abstraction -->|"delegates calls"| node_nativeclient
node_nativeclient -->|"uses auth"| node_auth
node_nativeclient -->|"opens listener"| node_realtime
node_abstraction -->|"exposes models"| node_models
node_nativechats -->|"maps chats"| node_models
node_nativemessages -->|"maps messages"| node_models
node_whatsappservice -->|"connects protocol"| node_nativeclient
node_realtime -->|"streams events"| node_listen

click node_main "https://github.com/gabrielfranicevich/wpp/blob/main/src/main.rs"
click node_cli "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/mod.rs"
click node_login "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/login.rs"
click node_sessions "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/session.rs"
click node_switch "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/switch.rs"
click node_logout "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/logout.rs"
click node_chatcmd "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/chat.rs"
click node_listcmd "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/list.rs"
click node_sendcmd "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/send.rs"
click node_synccmd "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/sync.rs"
click node_listen "https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/listen.rs"
click node_resolver "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chat_resolver.rs"
click node_listing "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chat_listing.rs"
click node_chatops "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chats.rs"
click node_messagepager "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/message_pager.rs"
click node_messages "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/messages.rs"
click node_syncservice "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/sync.rs"
click node_terminalpager "https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/pager.rs"
click node_composer "https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/composer.rs"
click node_render "https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/render.rs"
click node_context "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/state.rs"
click node_config "https://github.com/gabrielfranicevich/wpp/blob/main/src/app/config.rs"
click node_cache "https://github.com/gabrielfranicevich/wpp/blob/main/src/storage/sqlite.rs"
click node_abstraction "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/client.rs"
click node_models "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/models.rs"
click node_nativeclient "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/client.rs"
click node_auth "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/auth.rs"
click node_nativechats "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/chats.rs"
click node_nativemessages "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/messages.rs"
click node_realtime "https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/realtime.rs"

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_main,node_cli,node_login,node_sessions,node_switch,node_logout,node_chatcmd,node_listcmd,node_sendcmd,node_synccmd,node_listen,node_user toneBlue
class node_resolver,node_listing,node_chatops,node_messagepager,node_messages,node_syncservice toneAmber
class node_terminalpager,node_composer,node_render toneMint
class node_abstraction,node_models,node_nativeclient,node_auth,node_nativechats,node_nativemessages,node_realtime toneRose
class node_context,node_config,node_cache,node_whatsappservice toneIndigo
```

## Components

### CLI commands

- [Application entry](https://github.com/gabrielfranicevich/wpp/blob/main/src/main.rs): `src/main.rs`
- [Command router](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- [Login](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/login.rs): `src/cli/login.rs`
- [Session commands](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/session.rs): `src/cli/session.rs`
- [Switch session](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/switch.rs): `src/cli/switch.rs`
- [Logout](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/logout.rs): `src/cli/logout.rs`
- [Chat command](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/chat.rs): `src/cli/chat.rs`
- [List and search](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/list.rs): `src/cli/list.rs`
- [Send command](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/send.rs): `src/cli/send.rs`
- [Sync command](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/sync.rs): `src/cli/sync.rs`
- [Realtime listen](https://github.com/gabrielfranicevich/wpp/blob/main/src/cli/listen.rs): `src/cli/listen.rs`

### Application services

- [Chat resolution](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chat_resolver.rs): `src/app/services/chat_resolver.rs`
- [Chat listing](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chat_listing.rs): `src/app/services/chat_listing.rs`
- [Chat management](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/chats.rs): `src/app/services/chats.rs`
- [Message history](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/message_pager.rs): `src/app/services/message_pager.rs`
- [Message sending](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/messages.rs): `src/app/services/messages.rs`
- [Message sync](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/services/sync.rs): `src/app/services/sync.rs`

### Terminal interface

- [Interactive pager](https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/pager.rs): `src/terminal/pager.rs`
- [Message composer](https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/composer.rs): `src/terminal/composer.rs`
- [Terminal rendering](https://github.com/gabrielfranicevich/wpp/blob/main/src/terminal/render.rs): `src/terminal/render.rs`

### WhatsApp connectivity

- [WhatsApp abstraction](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/client.rs): `src/whatsapp/client.rs`
- [Domain models](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/models.rs): `src/whatsapp/models.rs`
- [Native client](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/client.rs): `src/whatsapp/native/client.rs`
- [Native authentication](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/auth.rs): `src/whatsapp/native/auth.rs`
- [Native chat operations](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/chats.rs): `src/whatsapp/native/chats.rs`
- [Native messaging](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/messages.rs): `src/whatsapp/native/messages.rs`
- [Realtime events](https://github.com/gabrielfranicevich/wpp/blob/main/src/whatsapp/native/realtime.rs): `src/whatsapp/native/realtime.rs`

### Session and cache

- [Active app context](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/state.rs): `src/app/state.rs`
- [Session configuration](https://github.com/gabrielfranicevich/wpp/blob/main/src/app/config.rs): `src/app/config.rs`
- [SQLite message cache](https://github.com/gabrielfranicevich/wpp/blob/main/src/storage/sqlite.rs): `src/storage/sqlite.rs`

### Other components

- **Terminal user**
- **WhatsApp service**

## Connections

- Terminal user → Application entry: runs (evidence: `README.md`)
- Application entry → Command router: dispatches (evidence: `src/main.rs`)
- Command router → Login: routes login (evidence: `src/cli/mod.rs`)
- Command router → Session commands: routes session (evidence: `src/cli/mod.rs`)
- Command router → Switch session: routes switch (evidence: `src/cli/mod.rs`)
- Command router → Logout: routes logout (evidence: `src/cli/mod.rs`)
- Command router → Chat command: routes chat (evidence: `src/cli/mod.rs`)
- Command router → List and search: routes list (evidence: `src/cli/mod.rs`)
- Command router → Send command: routes send (evidence: `src/cli/mod.rs`)
- Command router → Sync command: routes sync (evidence: `src/cli/mod.rs`)
- Command router → Realtime listen: routes listen (evidence: `src/cli/mod.rs`)
- Login → Native authentication: authenticates (evidence: `src/cli/login.rs`)
- Login → Session configuration: saves session (evidence: `README.md`)
- Switch session → Session configuration: selects session (evidence: `src/cli/switch.rs`)
- Logout → Session configuration: removes metadata (evidence: `src/cli/logout.rs`)
- Active app context → Session configuration: loads active session (evidence: `src/app/state.rs`)
- Active app context → WhatsApp abstraction: opens client (evidence: `src/app/state.rs`)
- Chat command → Chat resolution: resolves target (evidence: `src/cli/chat.rs`)
- Chat command → Chat management: manages chat (evidence: `src/cli/chat.rs`)
- Chat command → Message history: loads history (evidence: `src/cli/chat.rs`)
- Chat command → Interactive pager: opens pager (evidence: `src/cli/chat.rs`)
- List and search → Chat listing: lists chats (evidence: `src/cli/list.rs`)
- List and search → Terminal rendering: renders results (evidence: `src/cli/list.rs`)
- Send command → Chat resolution: resolves target (evidence: `src/cli/send.rs`)
- Send command → Message sending: sends text (evidence: `src/cli/send.rs`)
- Sync command → Message sync: starts sync (evidence: `src/cli/sync.rs`)
- Message sync → SQLite message cache: writes cache (evidence: `src/app/services/sync.rs`)
- Realtime listen → WhatsApp abstraction: opens listener (evidence: `README.md`)
- Interactive pager → Message composer: uses composer (evidence: `src/terminal/pager.rs`)
- Interactive pager → Message history: pages history (evidence: `src/terminal/pager.rs`)
- Interactive pager → WhatsApp abstraction: receives events (evidence: `README.md`)
- Chat resolution → WhatsApp abstraction: queries chats (evidence: `src/app/services/chat_resolver.rs`)
- Chat listing → WhatsApp abstraction: lists chats (evidence: `src/app/services/chat_listing.rs`)
- Chat management → WhatsApp abstraction: manages chats (evidence: `src/app/services/chats.rs`)
- Message history → WhatsApp abstraction: loads messages (evidence: `src/app/services/message_pager.rs`)
- Message history → Message sending: delegates sending (evidence: `src/app/services/message_pager.rs`)
- Message sending → WhatsApp abstraction: sends text (evidence: `src/app/services/messages.rs`)
- Message sync → WhatsApp abstraction: fetches messages (evidence: `src/app/services/sync.rs`)
- WhatsApp abstraction → Native client: delegates calls (evidence: `src/whatsapp/client.rs`)
- Native client → Native authentication: uses auth (evidence: `src/whatsapp/native/client.rs`)
- Native client → Realtime events: opens listener (evidence: `src/whatsapp/native/client.rs`)
- WhatsApp abstraction → Domain models: exposes models (evidence: `src/whatsapp/client.rs`)
- Native chat operations → Domain models: maps chats (evidence: `src/whatsapp/native/chats.rs`)
- Native messaging → Domain models: maps messages (evidence: `src/whatsapp/native/messages.rs`)
- WhatsApp service → Native client: connects protocol (evidence: `README.md`)
- Realtime events → Realtime listen: streams events (evidence: `README.md`)
