# mrloay/whatsapp-promo-broadcaster architecture

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

- Interactive diagram: https://gitdiagram.com/mrloay/whatsapp-promo-broadcaster
- Repository: https://github.com/mrloay/whatsapp-promo-broadcaster

## Overview

WhatsApp Boutique Broadcast is a small web dashboard and backend for managing opted-in contacts and sending personalized WhatsApp broadcasts. The main workflow is to sign in, import or maintain contacts, connect a WhatsApp session, then send a rate-limited campaign; inbound STOP messages suppress future sends. The graph includes campaign, account, template, credit, and webhook capabilities documented or indexed in the repository. Some route and UI details were not excerpted, so uncertain links are omitted.

Main entry points: [`src/server.ts`](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/server.ts) (HTTP server), [`src/services/campaigns.ts`](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/campaigns.ts) (Campaign orchestration), [`src/routes/webhook.ts`](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/webhook.ts) (Meta webhook), [`src/whatsapp/webjs-listeners.ts`](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/webjs-listeners.ts) (WhatsApp event listeners)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Dashboard and API"]
  node_dashboard["Web dashboard<br/>[index.html]"]
  node_server["HTTP server<br/>[server.ts]"]
  node_auth["Login and access<br/>[auth.ts]"]
  node_contact_api["Contact routes<br/>[contacts.ts]"]
  node_campaign_api["Campaign routes<br/>[campaigns.ts]"]
  node_wa_api["WhatsApp routes<br/>[whatsapp.ts]"]
  node_admin_api["Admin routes<br/>[admin.ts]"]
  node_system_api["System routes<br/>[system.ts]"]
  node_templates_api["Template routes<br/>[templates.ts]"]
  node_credits_api["Credit routes<br/>[credits.ts]"]
end

subgraph group_campaign["Broadcast management"]
  node_campaigns["Campaign orchestration<br/>[campaigns.ts]"]
  node_dispatch["Message dispatch<br/>[dispatch.ts]"]
  node_render["Message rendering<br/>[render.ts]"]
end

subgraph group_wa["WhatsApp integration"]
  node_webhook["Meta webhook<br/>[webhook.ts]"]
  node_signature["Webhook signature check<br/>[signature.ts]"]
  node_listeners["WhatsApp event listeners<br/>[webjs-listeners.ts]"]
  node_client["WhatsApp Web client<br/>[webjs-client.ts]"]
end

subgraph group_data["Persistence and services"]
  node_contacts["Contact and opt-in service<br/>[contacts.ts]"]
  node_templates["Template service<br/>[templates.ts]"]
  node_credits["Credit service<br/>[credits.ts]"]
  node_accounts["WhatsApp accounts<br/>[accounts.ts]"]
  node_db[("SQLite database<br/>[index.ts]")]
end

node_operator(("Boutique operator"))
node_whatsapp(("WhatsApp Web session"))

node_operator -->|"uses"| node_dashboard
node_dashboard -.->|"uses dashboard API"| node_server
node_server -->|"registers"| node_auth
node_server -->|"registers"| node_contact_api
node_server -->|"registers"| node_campaign_api
node_server -->|"registers"| node_wa_api
node_server -->|"registers"| node_admin_api
node_server -->|"registers"| node_system_api
node_server -->|"registers"| node_templates_api
node_server -->|"registers"| node_credits_api
node_server -->|"registers"| node_webhook
node_contact_api -->|"reads and writes"| node_db
node_contact_api -->|"calls"| node_contacts
node_campaign_api -->|"reads and writes"| node_db
node_campaign_api -->|"calls"| node_campaigns
node_campaign_api -->|"checks access"| node_auth
node_campaigns -->|"selects opted-in"| node_contacts
node_campaigns -->|"loads templates"| node_templates
node_campaigns -->|"checks and deducts"| node_credits
node_campaigns -->|"updates status"| node_accounts
node_campaigns -->|"sends messages"| node_dispatch
node_dispatch -->|"sends via"| node_client
node_dispatch -->|"renders content"| node_render
node_dispatch -->|"loads templates"| node_templates
node_wa_api -->|"checks and disconnects"| node_client
node_wa_api -->|"starts listeners"| node_listeners
node_wa_api -->|"manages accounts"| node_accounts
node_client -->|"drives session"| node_whatsapp
node_listeners -->|"wires events"| node_client
node_listeners -->|"marks opt-outs"| node_contacts
node_listeners -->|"records delivery"| node_campaigns
node_listeners -->|"updates status"| node_accounts
node_webhook -->|"verifies payload"| node_signature
node_webhook -->|"suppresses opt-outs"| node_contacts
node_webhook -->|"records delivery"| node_campaigns
node_webhook -->|"stores inbound messages"| node_db
node_templates_api -->|"calls"| node_templates
node_credits_api -->|"calls"| node_credits
node_admin_api -->|"manages credits"| node_credits
node_system_api -->|"manages accounts"| node_accounts

click node_dashboard "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/public/index.html"
click node_server "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/server.ts"
click node_auth "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/auth.ts"
click node_contact_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/contacts.ts"
click node_campaign_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/campaigns.ts"
click node_wa_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/whatsapp.ts"
click node_admin_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/admin.ts"
click node_system_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/system.ts"
click node_templates_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/templates.ts"
click node_credits_api "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/credits.ts"
click node_campaigns "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/campaigns.ts"
click node_dispatch "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/dispatch.ts"
click node_render "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/render.ts"
click node_contacts "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/contacts.ts"
click node_templates "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/templates.ts"
click node_credits "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/credits.ts"
click node_accounts "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/accounts.ts"
click node_db "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/db/index.ts"
click node_webhook "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/webhook.ts"
click node_signature "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/signature.ts"
click node_listeners "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/webjs-listeners.ts"
click node_client "https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/webjs-client.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_dashboard,node_server,node_auth,node_contact_api,node_campaign_api,node_wa_api,node_admin_api,node_system_api,node_templates_api,node_credits_api toneBlue
class node_campaigns,node_dispatch,node_render toneAmber
class node_webhook,node_signature,node_listeners,node_client toneMint
class node_contacts,node_templates,node_credits,node_accounts,node_db toneRose
class node_operator,node_whatsapp toneIndigo
```

## Components

### Dashboard and API

- [Web dashboard](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/public/index.html): `public/index.html`
- [HTTP server](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/server.ts): `src/server.ts`
- [Login and access](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/auth.ts): `src/auth.ts`
- [Contact routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/contacts.ts): `src/routes/contacts.ts`
- [Campaign routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/campaigns.ts): `src/routes/campaigns.ts`
- [WhatsApp routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/whatsapp.ts): `src/routes/whatsapp.ts`
- [Admin routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/admin.ts): `src/routes/admin.ts`
- [System routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/system.ts): `src/routes/system.ts`
- [Template routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/templates.ts): `src/routes/templates.ts`
- [Credit routes](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/credits.ts): `src/routes/credits.ts`

### Broadcast management

- [Campaign orchestration](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/campaigns.ts): `src/services/campaigns.ts`
- [Message dispatch](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/dispatch.ts): `src/whatsapp/dispatch.ts`
- [Message rendering](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/render.ts): `src/whatsapp/render.ts`

### WhatsApp integration

- [Meta webhook](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/routes/webhook.ts): `src/routes/webhook.ts`
- [Webhook signature check](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/signature.ts): `src/whatsapp/signature.ts`
- [WhatsApp event listeners](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/webjs-listeners.ts): `src/whatsapp/webjs-listeners.ts`
- [WhatsApp Web client](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/whatsapp/webjs-client.ts): `src/whatsapp/webjs-client.ts`

### Persistence and services

- [Contact and opt-in service](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/contacts.ts): `src/services/contacts.ts`
- [Template service](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/templates.ts): `src/services/templates.ts`
- [Credit service](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/credits.ts): `src/services/credits.ts`
- [WhatsApp accounts](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/services/accounts.ts): `src/services/accounts.ts`
- [SQLite database](https://github.com/mrloay/whatsapp-promo-broadcaster/blob/main/src/db/index.ts): `src/db/index.ts`

### Other components

- **Boutique operator**
- **WhatsApp Web session**

## Connections

- Boutique operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → HTTP server: uses dashboard API
- HTTP server → Login and access: registers (evidence: `src/server.ts`)
- HTTP server → Contact routes: registers (evidence: `src/server.ts`)
- HTTP server → Campaign routes: registers (evidence: `src/server.ts`)
- HTTP server → WhatsApp routes: registers (evidence: `src/server.ts`)
- HTTP server → Admin routes: registers (evidence: `src/server.ts`)
- HTTP server → System routes: registers (evidence: `src/server.ts`)
- HTTP server → Template routes: registers (evidence: `src/server.ts`)
- HTTP server → Credit routes: registers (evidence: `src/server.ts`)
- HTTP server → Meta webhook: registers (evidence: `src/server.ts`)
- Contact routes → SQLite database: reads and writes (evidence: `src/routes/contacts.ts`)
- Contact routes → Contact and opt-in service: calls (evidence: `src/routes/contacts.ts`)
- Campaign routes → SQLite database: reads and writes (evidence: `src/routes/campaigns.ts`)
- Campaign routes → Campaign orchestration: calls (evidence: `src/routes/campaigns.ts`)
- Campaign routes → Login and access: checks access (evidence: `src/routes/campaigns.ts`)
- Campaign orchestration → Contact and opt-in service: selects opted-in (evidence: `src/services/campaigns.ts`)
- Campaign orchestration → Template service: loads templates (evidence: `src/services/campaigns.ts`)
- Campaign orchestration → Credit service: checks and deducts (evidence: `src/services/campaigns.ts`)
- Campaign orchestration → WhatsApp accounts: updates status (evidence: `src/services/campaigns.ts`)
- Campaign orchestration → Message dispatch: sends messages (evidence: `src/services/campaigns.ts`)
- Message dispatch → WhatsApp Web client: sends via (evidence: `src/whatsapp/dispatch.ts`)
- Message dispatch → Message rendering: renders content (evidence: `src/whatsapp/dispatch.ts`)
- Message dispatch → Template service: loads templates (evidence: `src/whatsapp/dispatch.ts`)
- WhatsApp routes → WhatsApp Web client: checks and disconnects (evidence: `src/routes/whatsapp.ts`)
- WhatsApp routes → WhatsApp event listeners: starts listeners (evidence: `src/routes/whatsapp.ts`)
- WhatsApp routes → WhatsApp accounts: manages accounts (evidence: `src/routes/whatsapp.ts`)
- WhatsApp Web client → WhatsApp Web session: drives session (evidence: `src/whatsapp/webjs-client.ts`)
- WhatsApp event listeners → WhatsApp Web client: wires events (evidence: `src/whatsapp/webjs-listeners.ts`)
- WhatsApp event listeners → Contact and opt-in service: marks opt-outs (evidence: `src/whatsapp/webjs-listeners.ts`)
- WhatsApp event listeners → Campaign orchestration: records delivery (evidence: `src/whatsapp/webjs-listeners.ts`)
- WhatsApp event listeners → WhatsApp accounts: updates status (evidence: `src/whatsapp/webjs-listeners.ts`)
- Meta webhook → Webhook signature check: verifies payload (evidence: `src/routes/webhook.ts`)
- Meta webhook → Contact and opt-in service: suppresses opt-outs (evidence: `src/routes/webhook.ts`)
- Meta webhook → Campaign orchestration: records delivery (evidence: `src/routes/webhook.ts`)
- Meta webhook → SQLite database: stores inbound messages (evidence: `src/routes/webhook.ts`)
- Template routes → Template service: calls (evidence: `src/routes/templates.ts`)
- Credit routes → Credit service: calls (evidence: `src/routes/credits.ts`)
- Admin routes → Credit service: manages credits (evidence: `src/routes/admin.ts`)
- System routes → WhatsApp accounts: manages accounts (evidence: `src/routes/system.ts`)