# dsebastien/whatsapp-claude-agent architecture

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

- Interactive diagram: https://gitdiagram.com/dsebastien/whatsapp-claude-agent
- Repository: https://github.com/dsebastien/whatsapp-claude-agent

## Overview

WhatsApp Claude Agent accepts phone and group messages, filters them through whitelist/targeting rules, routes commands or conversation prompts, invokes Claude Code in a configured working directory, and sends responses back over WhatsApp. The graph captures CLI/configuration, messaging, conversation state, and Claude execution; several links rely on the SOURCE INDEX or README because implementation excerpts are partial.

Main entry points: [`src/whatsapp/client.ts`](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/client.ts) (WhatsApp client), [`src/conversation/manager.ts`](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/manager.ts) (Conversation manager), [`src/index.ts`](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/index.ts) (Runtime orchestrator), [`src/claude/backend.ts`](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/backend.ts) (Claude backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_cli["CLI commands<br/>[commands.ts]"]
  node_config["Configuration<br/>[config.ts]"]
  node_config_cmds["Config commands<br/>[config-commands.ts]"]
  node_agent_name["Agent identity<br/>[agent-name.ts]"]
  node_app["Runtime orchestrator<br/>[index.ts]"]
end

subgraph group_messaging["WhatsApp messaging"]
  node_whatsapp["WhatsApp client<br/>[client.ts]"]
  node_wa_service(("WhatsApp network"))
  node_auth[("Auth persistence<br/>[auth.ts]")]
  node_message_parse["Message parsing<br/>[messages.ts]"]
  node_chunker["Response chunking<br/>[chunker.ts]"]
  node_phone["Phone filtering<br/>[phone.ts]"]
end

subgraph group_conversation["Conversation workflow"]
  node_manager["Conversation manager<br/>[manager.ts]"]
  node_history["Conversation history<br/>[history.ts]"]
  node_queue["Message queue<br/>[queue.ts]"]
end

subgraph group_claude["Claude execution"]
  node_backend["Claude backend<br/>[backend.ts]"]
  node_sdk["SDK backend<br/>[sdk-backend.ts]"]
  node_permissions["Permission modes<br/>[permissions.ts]"]
  node_model_utils["Model selection<br/>[utils.ts]"]
end

node_user(("WhatsApp user"))
node_workspace[("Working files")]
node_claude_sdk(("Claude Agent SDK"))

node_user -->|"sends messages"| node_wa_service
node_wa_service -->|"delivers events"| node_whatsapp
node_whatsapp -->|"loads session"| node_auth
node_whatsapp -->|"parses incoming"| node_message_parse
node_whatsapp -->|"checks whitelist"| node_phone
node_whatsapp -->|"emits events"| node_app
node_app -->|"parses options"| node_cli
node_cli -->|"loads configuration"| node_config
node_cli -->|"registers subcommand"| node_config_cmds
node_config -->|"generates identity"| node_agent_name
node_app -->|"creates client"| node_whatsapp
node_app -->|"creates SDK backend"| node_backend
node_app -->|"creates manager"| node_manager
node_app -->|"routes messages"| node_manager
node_manager -->|"parses commands"| node_message_parse
node_manager -->|"checks group targeting"| node_agent_name
node_manager -->|"updates history"| node_history
node_manager -->|"uses queue"| node_queue
node_manager -->|"submits prompts"| node_backend
node_backend -->|"resolves model"| node_model_utils
node_backend -.->|"implements backend"| node_sdk
node_sdk -->|"runs queries"| node_claude_sdk
node_sdk -.->|"applies modes"| node_permissions
node_claude_sdk -->|"acts on files"| node_workspace
node_manager -.->|"sends responses"| node_whatsapp
node_whatsapp -.->|"splits responses"| node_chunker
node_whatsapp -.->|"sends messages"| node_wa_service

click node_cli "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/commands.ts"
click node_config "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/config.ts"
click node_config_cmds "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/config-commands.ts"
click node_agent_name "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/utils/agent-name.ts"
click node_app "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/index.ts"
click node_whatsapp "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/client.ts"
click node_auth "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/auth.ts"
click node_message_parse "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/messages.ts"
click node_chunker "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/chunker.ts"
click node_phone "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/utils/phone.ts"
click node_manager "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/manager.ts"
click node_history "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/history.ts"
click node_queue "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/queue.ts"
click node_backend "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/backend.ts"
click node_sdk "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/sdk-backend.ts"
click node_permissions "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/permissions.ts"
click node_model_utils "https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/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_cli,node_config,node_config_cmds,node_agent_name,node_app,node_user toneBlue
class node_whatsapp,node_wa_service,node_auth,node_message_parse,node_chunker,node_phone,node_workspace toneAmber
class node_manager,node_history,node_queue toneMint
class node_backend,node_sdk,node_permissions,node_model_utils toneRose
class node_claude_sdk toneIndigo
```

## Components

### Startup and configuration

- [CLI commands](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/commands.ts): `src/cli/commands.ts`
- [Configuration](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/config.ts): `src/cli/config.ts`
- [Config commands](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/cli/config-commands.ts): `src/cli/config-commands.ts`
- [Agent identity](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/utils/agent-name.ts): `src/utils/agent-name.ts`
- [Runtime orchestrator](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/index.ts): `src/index.ts`

### WhatsApp messaging

- [WhatsApp client](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/client.ts): `src/whatsapp/client.ts`
- **WhatsApp network**
- [Auth persistence](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/auth.ts): `src/whatsapp/auth.ts`
- [Message parsing](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/messages.ts): `src/whatsapp/messages.ts`
- [Response chunking](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/whatsapp/chunker.ts): `src/whatsapp/chunker.ts`
- [Phone filtering](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/utils/phone.ts): `src/utils/phone.ts`

### Conversation workflow

- [Conversation manager](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/manager.ts): `src/conversation/manager.ts`
- [Conversation history](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/history.ts): `src/conversation/history.ts`
- [Message queue](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/conversation/queue.ts): `src/conversation/queue.ts`

### Claude execution

- [Claude backend](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/backend.ts): `src/claude/backend.ts`
- [SDK backend](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/sdk-backend.ts): `src/claude/sdk-backend.ts`
- [Permission modes](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/permissions.ts): `src/claude/permissions.ts`
- [Model selection](https://github.com/dsebastien/whatsapp-claude-agent/blob/main/src/claude/utils.ts): `src/claude/utils.ts`

### Other components

- **WhatsApp user**
- **Working files**
- **Claude Agent SDK**

## Connections

- WhatsApp user → WhatsApp network: sends messages (evidence: `README.md`)
- WhatsApp network → WhatsApp client: delivers events (evidence: `src/whatsapp/client.ts`)
- WhatsApp client → Auth persistence: loads session (evidence: `src/whatsapp/client.ts`)
- WhatsApp client → Message parsing: parses incoming (evidence: `src/whatsapp/client.ts`)
- WhatsApp client → Phone filtering: checks whitelist (evidence: `src/whatsapp/client.ts`)
- WhatsApp client → Runtime orchestrator: emits events (evidence: `src/index.ts`)
- Runtime orchestrator → CLI commands: parses options (evidence: `src/index.ts`)
- CLI commands → Configuration: loads configuration (evidence: `src/cli/commands.ts`)
- CLI commands → Config commands: registers subcommand (evidence: `src/cli/commands.ts`)
- Configuration → Agent identity: generates identity (evidence: `src/cli/config.ts`)
- Runtime orchestrator → WhatsApp client: creates client (evidence: `src/index.ts`)
- Runtime orchestrator → Claude backend: creates SDK backend (evidence: `src/index.ts`)
- Runtime orchestrator → Conversation manager: creates manager (evidence: `src/index.ts`)
- Runtime orchestrator → Conversation manager: routes messages (evidence: `src/index.ts`)
- Conversation manager → Message parsing: parses commands (evidence: `src/conversation/manager.ts`)
- Conversation manager → Agent identity: checks group targeting (evidence: `src/conversation/manager.ts`)
- Conversation manager → Conversation history: updates history (evidence: `src/conversation/manager.ts`)
- Conversation manager → Message queue: uses queue (evidence: `src/conversation/manager.ts`)
- Conversation manager → Claude backend: submits prompts (evidence: `src/conversation/manager.ts`)
- Claude backend → Model selection: resolves model (evidence: `src/claude/backend.ts`)
- Claude backend → SDK backend: implements backend (evidence: `src/claude/sdk-backend.ts`)
- SDK backend → Claude Agent SDK: runs queries (evidence: `src/claude/sdk-backend.ts`)
- SDK backend → Permission modes: applies modes
- Claude Agent SDK → Working files: acts on files (evidence: `README.md`)
- Conversation manager → WhatsApp client: sends responses (evidence: `src/conversation/manager.ts`)
- WhatsApp client → Response chunking: splits responses (evidence: `src/whatsapp/client.ts`)
- WhatsApp client → WhatsApp network: sends messages
