# ronendotan/whatsapp-claude-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/ronendotan/whatsapp-claude-bridge
- Repository: https://github.com/ronendotan/whatsapp-claude-bridge

## Overview

WhatsApp & Signal ↔ Claude/Codex Bridge accepts messages per allowed chat, processes commands and media, resumes a per-chat LLM session, then sends replies through the originating channel. A separate Python MCP server exposes WhatsApp history and messaging tools. The README documents major capabilities such as per-chat personalities, working directories, transcription, and admin controls; unsampled modules are represented only where the tree supports their paths, so uncertain internal links are omitted.

Main entry points: [`whatsapp-bridge/main.go`](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/main.go) (Bridge dispatcher), [`whatsapp-bridge/core/process.go`](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/process.go) (Message processing), [`whatsapp-bridge/llms/claude/llm.go`](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/claude/llm.go) (Claude adapter), [`whatsapp-bridge/llms/codex/llm.go`](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/codex/llm.go) (Codex adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Message channels"]
  node_wa_channel["WhatsApp channel<br/>[channel.go]"]
  node_wa_handler["WhatsApp handler<br/>[handler.go]"]
  node_signal_channel["Signal channel<br/>[channel.go]"]
  node_signal_handler["Signal handler<br/>[handler.go]"]
  node_message_store[("WhatsApp message store<br/>[handler.go]")]
  node_reply_channel["Channel sender<br/>[handler.go]"]
end

subgraph group_runtime["Bridge runtime"]
  node_main["Bridge dispatcher<br/>[main.go]"]
  node_core_process["Message processing<br/>[process.go]"]
  node_core_commands["Bridge commands<br/>[commands.go]"]
  node_core_allowed["Chat access rules<br/>[allowed.go]"]
  node_core_personality["Personalities<br/>[personalities.go]"]
  node_core_transcribe["Audio transcription<br/>[transcribe.go]"]
  node_session_state[("Session state<br/>[sessions.go]")]
end

subgraph group_llm["LLM processing"]
  node_claude["Claude adapter<br/>[llm.go]"]
  node_codex["Codex adapter<br/>[llm.go]"]
end

subgraph group_admin["Admin console"]
  node_admin_server["Admin HTTP API<br/>[server.go]"]
  node_admin_handlers["Admin handlers<br/>[handlers.go]"]
  node_admin_ui["Admin web UI<br/>[app.js]"]
end

subgraph group_mcp["MCP access"]
  node_mcp_tools["WhatsApp MCP tools<br/>[main.py]"]
  node_mcp_data["WhatsApp data access<br/>[whatsapp.py]"]
end

node_wa_actor(("WhatsApp users"))
node_signal_actor(("Signal users"))
node_claude_cli["Claude CLI"]
node_codex_cli["Codex CLI"]
node_whatsapp_db[("WhatsApp message database")]
node_bridge_api["Bridge REST API"]

node_wa_actor -->|"sends messages"| node_wa_channel
node_signal_actor -->|"sends messages"| node_signal_channel
node_wa_channel -->|"delivers events"| node_wa_handler
node_signal_channel -->|"delivers events"| node_signal_handler
node_wa_handler -->|"queues messages"| node_main
node_signal_handler -->|"queues messages"| node_main
node_main -->|"dispatches commands"| node_core_commands
node_main -->|"checks access"| node_core_allowed
node_main -->|"processes events"| node_core_process
node_core_process -->|"transcribes audio"| node_core_transcribe
node_core_process -->|"loads context"| node_core_personality
node_core_process -->|"invokes selected LLM"| node_claude
node_core_process -->|"invokes selected LLM"| node_codex
node_claude -->|"reads and saves"| node_session_state
node_codex -->|"reads and saves"| node_session_state
node_claude -->|"runs subprocess"| node_claude_cli
node_codex -->|"runs subprocess"| node_codex_cli
node_main -->|"sends replies"| node_reply_channel
node_admin_ui -->|"calls API"| node_admin_server
node_admin_server -->|"routes requests"| node_admin_handlers
node_admin_handlers -->|"reads and updates"| node_core_allowed
node_admin_handlers -->|"runs admin prompts"| node_core_process
node_mcp_tools -->|"calls tools"| node_mcp_data
node_mcp_data -->|"queries history"| node_whatsapp_db
node_mcp_data -->|"sends messages"| node_bridge_api
node_bridge_api -.->|"dispatches send"| node_wa_handler

click node_wa_channel "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/channel.go"
click node_wa_handler "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go"
click node_signal_channel "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/signal/channel.go"
click node_signal_handler "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/signal/handler.go"
click node_main "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/main.go"
click node_core_process "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/process.go"
click node_core_commands "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/commands.go"
click node_core_allowed "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/allowed.go"
click node_core_personality "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/personalities.go"
click node_core_transcribe "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/transcribe.go"
click node_session_state "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/sessions.go"
click node_message_store "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go"
click node_claude "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/claude/llm.go"
click node_codex "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/codex/llm.go"
click node_reply_channel "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go"
click node_admin_server "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/server.go"
click node_admin_handlers "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/handlers.go"
click node_admin_ui "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/static/app.js"
click node_mcp_tools "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-mcp-server/main.py"
click node_mcp_data "https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-mcp-server/whatsapp.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_wa_channel,node_wa_handler,node_signal_channel,node_signal_handler,node_message_store,node_reply_channel,node_wa_actor,node_signal_actor toneBlue
class node_main,node_core_process,node_core_commands,node_core_allowed,node_core_personality,node_core_transcribe,node_session_state,node_whatsapp_db toneAmber
class node_claude,node_codex,node_bridge_api toneMint
class node_admin_server,node_admin_handlers,node_admin_ui toneRose
class node_mcp_tools,node_mcp_data,node_claude_cli,node_codex_cli toneIndigo
```

## Components

### Message channels

- [WhatsApp channel](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/channel.go): `whatsapp-bridge/channels/whatsapp/channel.go`
- [WhatsApp handler](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go): `whatsapp-bridge/channels/whatsapp/handler.go`
- [Signal channel](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/signal/channel.go): `whatsapp-bridge/channels/signal/channel.go`
- [Signal handler](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/signal/handler.go): `whatsapp-bridge/channels/signal/handler.go`
- [WhatsApp message store](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go): `whatsapp-bridge/channels/whatsapp/handler.go`
- [Channel sender](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/channels/whatsapp/handler.go): `whatsapp-bridge/channels/whatsapp/handler.go`

### Bridge runtime

- [Bridge dispatcher](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/main.go): `whatsapp-bridge/main.go`
- [Message processing](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/process.go): `whatsapp-bridge/core/process.go`
- [Bridge commands](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/commands.go): `whatsapp-bridge/core/commands.go`
- [Chat access rules](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/allowed.go): `whatsapp-bridge/core/allowed.go`
- [Personalities](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/personalities.go): `whatsapp-bridge/core/personalities.go`
- [Audio transcription](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/transcribe.go): `whatsapp-bridge/core/transcribe.go`
- [Session state](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/core/sessions.go): `whatsapp-bridge/core/sessions.go`

### LLM processing

- [Claude adapter](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/claude/llm.go): `whatsapp-bridge/llms/claude/llm.go`
- [Codex adapter](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/llms/codex/llm.go): `whatsapp-bridge/llms/codex/llm.go`

### Admin console

- [Admin HTTP API](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/server.go): `whatsapp-bridge/admin/server.go`
- [Admin handlers](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/handlers.go): `whatsapp-bridge/admin/handlers.go`
- [Admin web UI](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-bridge/admin/static/app.js): `whatsapp-bridge/admin/static/app.js`

### MCP access

- [WhatsApp MCP tools](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-mcp-server/main.py): `whatsapp-mcp-server/main.py`
- [WhatsApp data access](https://github.com/ronendotan/whatsapp-claude-bridge/blob/main/whatsapp-mcp-server/whatsapp.py): `whatsapp-mcp-server/whatsapp.py`

### Other components

- **WhatsApp users**
- **Signal users**
- **Claude CLI**
- **Codex CLI**
- **WhatsApp message database**
- **Bridge REST API**

## Connections

- WhatsApp users → WhatsApp channel: sends messages
- Signal users → Signal channel: sends messages
- WhatsApp channel → WhatsApp handler: delivers events
- Signal channel → Signal handler: delivers events
- WhatsApp handler → Bridge dispatcher: queues messages
- Signal handler → Bridge dispatcher: queues messages
- Bridge dispatcher → Bridge commands: dispatches commands
- Bridge dispatcher → Chat access rules: checks access
- Bridge dispatcher → Message processing: processes events
- Message processing → Audio transcription: transcribes audio
- Message processing → Personalities: loads context
- Message processing → Claude adapter: invokes selected LLM
- Message processing → Codex adapter: invokes selected LLM
- Claude adapter → Session state: reads and saves
- Codex adapter → Session state: reads and saves
- Claude adapter → Claude CLI: runs subprocess
- Codex adapter → Codex CLI: runs subprocess
- Bridge dispatcher → Channel sender: sends replies
- Admin web UI → Admin HTTP API: calls API
- Admin HTTP API → Admin handlers: routes requests
- Admin handlers → Chat access rules: reads and updates
- Admin handlers → Message processing: runs admin prompts
- WhatsApp MCP tools → WhatsApp data access: calls tools
- WhatsApp data access → WhatsApp message database: queries history
- WhatsApp data access → Bridge REST API: sends messages
- Bridge REST API → WhatsApp handler: dispatches send