# eitaar/dsh-whatsapp-connector architecture

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

- Interactive diagram: https://gitdiagram.com/eitaar/dsh-whatsapp-connector
- Repository: https://github.com/eitaar/dsh-whatsapp-connector

## Overview

DSH WhatsApp Connector links WhatsApp Web to a local DeepSeek Harness. The main flow is browser setup and QR provisioning, host RPC, controller-managed WhatsApp runtime/session, inbound message and file handling, Harness session execution, then streamed replies and artifacts delivered back through WhatsApp. The README also documents access policies, bot/session/workspace and Agent Preset controls, model and reasoning commands, approvals, batch input, and file transfer. Unsampled runtime modules are represented at their exact paths; edges are limited to relationships evidenced by the README or source index.

Main entry points: [`src/channels/whatsapp/whatsapp-runtime.mjs`](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-runtime.mjs) (WhatsApp Runtime), [`src/channels/shared/harness-client.mjs`](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/harness-client.mjs) (Harness Client), [`plugin-src/host/channels/whatsapp/production.mjs`](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/whatsapp/production.mjs) (WhatsApp Production), [`src/channels/whatsapp/whatsapp-controller.mjs`](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-controller.mjs) (Bot Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_settings["Settings UI"]
  node_settings_ui["Connector Settings<br/>[index.js]"]
  node_client_entry["Client Plugin<br/>[index.js]"]
  node_wa_rpc_ui["WhatsApp RPC Client<br/>[api.js]"]
  node_workspace_ui["Workspace Editor"]
end

subgraph group_host["Plugin Host"]
  node_host_rpc["Host RPC<br/>[rpc.mjs]"]
  node_host_entry["Host Plugin<br/>[index.mjs]"]
  node_production["WhatsApp Production<br/>[production.mjs]"]
  node_supervisor["Connection Supervisor"]
end

subgraph group_wa["WhatsApp Runtime"]
  node_controller["Bot Controller"]
  node_runtime["WhatsApp Runtime"]
  node_web_session["Web Session"]
  node_config[("Bot Configuration<br/>[config-store.mjs]")]
  node_wa_state[("Session State<br/>[state-store.mjs]")]
  node_wa_bridge["WhatsApp Bridge"]
end

subgraph group_harness["Harness Workflow"]
  node_session_coord["Session Coordinator"]
  node_harness_client["Harness Client<br/>[harness-client.mjs]"]
  node_wa_harness_client["WhatsApp Harness Adapter<br/>[harness-client.mjs]"]
end

subgraph group_shared["Shared Features"]
  node_workspace_store[("Workspace Store")]
  node_agent_preset["Agent Presets<br/>[agent-preset.mjs]"]
  node_inbound_files["Inbound Files<br/>[inbound-file.mjs]"]
  node_artifacts["Artifact Handling<br/>[artifact.mjs]"]
  node_commands["Bot Commands<br/>[model-command.mjs]"]
  node_approval["Interactive Approvals"]
  node_i18n["Host Translations<br/>[i18n.mjs]"]
end

node_user(("Operator"))
node_whatsapp_user(("WhatsApp User"))
node_browser(("Browser"))
node_wa_service{{"WhatsApp Web"}}
node_dsh{{"DeepSeek Harness"}}

node_user -->|"opens settings"| node_browser
node_browser -->|"configures bot"| node_settings_ui
node_client_entry -->|"registers settings"| node_settings_ui
node_settings_ui -->|"calls endpoints"| node_wa_rpc_ui
node_settings_ui -->|"edits workspace"| node_workspace_ui
node_wa_rpc_ui -.->|"sends RPC"| node_host_rpc
node_host_rpc -->|"manages bots"| node_controller
node_host_entry -->|"registers runtime"| node_production
node_production -->|"uses supervision"| node_supervisor
node_production -->|"constructs controller"| node_controller
node_controller -->|"reads and saves"| node_config
node_controller -.->|"starts and stops"| node_runtime
node_runtime -.->|"uses session"| node_web_session
node_runtime -.->|"routes messages"| node_wa_bridge
node_runtime -.->|"persists state"| node_wa_state
node_web_session -->|"connects"| node_wa_service
node_whatsapp_user -->|"sends messages"| node_wa_service
node_wa_service -.->|"delivers messages"| node_runtime
node_runtime -.->|"coordinates sessions"| node_session_coord
node_session_coord -->|"coordinates actions"| node_harness_client
node_harness_client -->|"uses Harness RPC"| node_dsh
node_harness_client -->|"stages files"| node_inbound_files
node_session_coord -->|"stages ingress"| node_inbound_files
node_runtime -.->|"uses adapter"| node_wa_harness_client
node_wa_harness_client -->|"extends client"| node_harness_client
node_harness_client -.->|"streams replies"| node_runtime
node_runtime -->|"edits progress messages"| node_wa_service
node_workspace_store -->|"uses presets"| node_agent_preset
node_production -->|"configures storage"| node_workspace_store
node_production -->|"configures presets"| node_agent_preset
node_harness_client -->|"handles artifacts"| node_artifacts
node_runtime -->|"supports commands"| node_commands
node_runtime -->|"supports approvals"| node_approval
node_controller -->|"translates messages"| node_i18n
node_runtime -->|"applies access policy"| node_wa_service

click node_settings_ui "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/channels/whatsapp/index.js"
click node_client_entry "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/index.js"
click node_wa_rpc_ui "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/channels/whatsapp/api.js"
click node_workspace_ui "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/workspace-editor.js"
click node_host_rpc "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/whatsapp/rpc.mjs"
click node_host_entry "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/index.mjs"
click node_production "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/whatsapp/production.mjs"
click node_supervisor "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/shared/connection-supervisor.mjs"
click node_controller "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-controller.mjs"
click node_runtime "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-runtime.mjs"
click node_web_session "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-web-session.mjs"
click node_config "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/config-store.mjs"
click node_wa_state "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/state-store.mjs"
click node_wa_bridge "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-bridge.mjs"
click node_session_coord "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/harness-session-coordinator.mjs"
click node_harness_client "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/harness-client.mjs"
click node_wa_harness_client "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/harness-client.mjs"
click node_workspace_store "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/bot-workspace-store.mjs"
click node_agent_preset "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/agent-preset.mjs"
click node_inbound_files "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/inbound-file.mjs"
click node_artifacts "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/semantic/artifact.mjs"
click node_commands "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/model-command.mjs"
click node_approval "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/harness-approval.mjs"
click node_i18n "https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/i18n.mjs"

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_settings_ui,node_client_entry,node_wa_rpc_ui,node_workspace_ui,node_whatsapp_user,node_browser toneBlue
class node_host_rpc,node_host_entry,node_production,node_supervisor toneAmber
class node_controller,node_runtime,node_web_session,node_config,node_wa_state,node_wa_bridge toneMint
class node_session_coord,node_harness_client,node_wa_harness_client toneRose
class node_workspace_store,node_agent_preset,node_inbound_files,node_artifacts,node_commands,node_approval,node_i18n,node_user,node_wa_service,node_dsh toneIndigo
```

## Components

### Settings UI

- [Connector Settings](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/channels/whatsapp/index.js): `plugin-src/client/channels/whatsapp/index.js`
- [Client Plugin](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/index.js): `plugin-src/client/index.js`
- [WhatsApp RPC Client](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/channels/whatsapp/api.js): `plugin-src/client/channels/whatsapp/api.js`
- [Workspace Editor](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/client/workspace-editor.js): `plugin-src/client/workspace-editor.js`

### Plugin Host

- [Host RPC](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/whatsapp/rpc.mjs): `plugin-src/host/channels/whatsapp/rpc.mjs`
- [Host Plugin](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/index.mjs): `plugin-src/host/index.mjs`
- [WhatsApp Production](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/whatsapp/production.mjs): `plugin-src/host/channels/whatsapp/production.mjs`
- [Connection Supervisor](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/channels/shared/connection-supervisor.mjs): `plugin-src/host/channels/shared/connection-supervisor.mjs`

### WhatsApp Runtime

- [Bot Controller](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-controller.mjs): `src/channels/whatsapp/whatsapp-controller.mjs`
- [WhatsApp Runtime](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-runtime.mjs): `src/channels/whatsapp/whatsapp-runtime.mjs`
- [Web Session](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-web-session.mjs): `src/channels/whatsapp/whatsapp-web-session.mjs`
- [Bot Configuration](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/config-store.mjs): `src/channels/whatsapp/config-store.mjs`
- [Session State](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/state-store.mjs): `src/channels/whatsapp/state-store.mjs`
- [WhatsApp Bridge](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/whatsapp-bridge.mjs): `src/channels/whatsapp/whatsapp-bridge.mjs`

### Harness Workflow

- [Session Coordinator](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/plugin-src/host/harness-session-coordinator.mjs): `plugin-src/host/harness-session-coordinator.mjs`
- [Harness Client](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/harness-client.mjs): `src/channels/shared/harness-client.mjs`
- [WhatsApp Harness Adapter](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/whatsapp/harness-client.mjs): `src/channels/whatsapp/harness-client.mjs`

### Shared Features

- [Workspace Store](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/bot-workspace-store.mjs): `src/channels/shared/bot-workspace-store.mjs`
- [Agent Presets](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/agent-preset.mjs): `src/channels/shared/agent-preset.mjs`
- [Inbound Files](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/inbound-file.mjs): `src/channels/shared/inbound-file.mjs`
- [Artifact Handling](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/semantic/artifact.mjs): `src/channels/shared/semantic/artifact.mjs`
- [Bot Commands](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/model-command.mjs): `src/channels/shared/model-command.mjs`
- [Interactive Approvals](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/harness-approval.mjs): `src/channels/shared/harness-approval.mjs`
- [Host Translations](https://github.com/eitaar/dsh-whatsapp-connector/blob/main/src/channels/shared/i18n.mjs): `src/channels/shared/i18n.mjs`

### Other components

- **Operator**
- **WhatsApp User**
- **Browser**
- **WhatsApp Web**
- **DeepSeek Harness**

## Connections

- Operator → Browser: opens settings (evidence: `README.md`)
- Browser → Connector Settings: configures bot (evidence: `README.md`)
- Client Plugin → Connector Settings: registers settings (evidence: `plugin-src/client/index.js`)
- Connector Settings → WhatsApp RPC Client: calls endpoints (evidence: `plugin-src/client/channels/whatsapp/index.js`)
- Connector Settings → Workspace Editor: edits workspace (evidence: `plugin-src/client/channels/whatsapp/index.js`)
- WhatsApp RPC Client → Host RPC: sends RPC
- Host RPC → Bot Controller: manages bots (evidence: `plugin-src/host/channels/whatsapp/rpc.mjs`)
- Host Plugin → WhatsApp Production: registers runtime (evidence: `plugin-src/host/index.mjs`)
- WhatsApp Production → Connection Supervisor: uses supervision (evidence: `plugin-src/host/channels/whatsapp/production.mjs`)
- WhatsApp Production → Bot Controller: constructs controller (evidence: `plugin-src/host/channels/whatsapp/production.mjs`)
- Bot Controller → Bot Configuration: reads and saves (evidence: `src/channels/whatsapp/whatsapp-controller.mjs`)
- Bot Controller → WhatsApp Runtime: starts and stops
- WhatsApp Runtime → Web Session: uses session
- WhatsApp Runtime → WhatsApp Bridge: routes messages
- WhatsApp Runtime → Session State: persists state
- Web Session → WhatsApp Web: connects (evidence: `README.md`)
- WhatsApp User → WhatsApp Web: sends messages (evidence: `README.md`)
- WhatsApp Web → WhatsApp Runtime: delivers messages
- WhatsApp Runtime → Session Coordinator: coordinates sessions
- Session Coordinator → Harness Client: coordinates actions (evidence: `plugin-src/host/harness-session-coordinator.mjs`)
- Harness Client → DeepSeek Harness: uses Harness RPC (evidence: `README.md`)
- Harness Client → Inbound Files: stages files (evidence: `src/channels/shared/harness-client.mjs`)
- Session Coordinator → Inbound Files: stages ingress (evidence: `plugin-src/host/harness-session-coordinator.mjs`)
- WhatsApp Runtime → WhatsApp Harness Adapter: uses adapter
- WhatsApp Harness Adapter → Harness Client: extends client (evidence: `src/channels/whatsapp/harness-client.mjs`)
- Harness Client → WhatsApp Runtime: streams replies
- WhatsApp Runtime → WhatsApp Web: edits progress messages (evidence: `README.md`)
- Workspace Store → Agent Presets: uses presets (evidence: `src/channels/shared/bot-workspace-store.mjs`)
- WhatsApp Production → Workspace Store: configures storage (evidence: `plugin-src/host/channels/whatsapp/production.mjs`)
- WhatsApp Production → Agent Presets: configures presets (evidence: `plugin-src/host/channels/whatsapp/production.mjs`)
- Harness Client → Artifact Handling: handles artifacts (evidence: `src/channels/shared/harness-client.mjs`)
- WhatsApp Runtime → Bot Commands: supports commands (evidence: `README.md`)
- WhatsApp Runtime → Interactive Approvals: supports approvals (evidence: `README.md`)
- Bot Controller → Host Translations: translates messages (evidence: `src/channels/whatsapp/whatsapp-controller.mjs`)
- WhatsApp Runtime → WhatsApp Web: applies access policy (evidence: `README.md`)
