# hashirbot/whats-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/hashirbot/whats-bridge
- Repository: https://github.com/hashirbot/whats-bridge

## Overview

WhatsBridge is organized as a single Go service that combines a WhatsApp connection layer, an HTTP/WebSocket API, a small web dashboard, and persistence for sessions, scheduling, and metrics.

At the top level, `main.go` is the application entrypoint. It wires together the internal packages, starts the server, and binds to the deployment port expected by Docker/Koyeb (`PORT`, with local fallback behavior described in the README).

The architecture breaks into these main subsystems:

- `internal/bot/`
  - This is the core WhatsApp integration layer built around `whatsmeow`.
  - `bot.go` likely owns the lifecycle of the WhatsApp client: connect, disconnect, send messages, and expose current connection state.
  - `bridge.go` is the real-time relay boundary for the `/ws/bridge` endpoint, translating between external apps and WhatsApp events/messages.
  - `monitor.go` implements the watchdog behavior described in the README: detect lost connectivity and reconnect.
  - `scheduler.go` handles deferred or bulk message dispatch, probably consuming scheduled items from storage and handing them to the bot for delivery.

- `internal/api/handlers.go`
  - This is the HTTP surface area for the dashboard and external integrations.
  - The README’s endpoints map here: `/api/status`, `/api/send`, `/api/bulk-send`, `/api/schedule`, `/api/qr`, `/api/metrics`, `/api/connect`, `/api/disconnect`, `/api/logout`, plus the WebSocket bridge at `/ws/bridge`.
  - This layer is the boundary between clients and the core bot logic: it validates requests, applies auth, and delegates work to `internal/bot` and `internal/db`.

- `internal/auth/auth.go`
  - This package is the authentication/authorization boundary for the dashboard and API access.
  - Given the presence of `public/login.html` and `public/api-keys.html`, this likely handles user/session/API-key checks before allowing access to bot control and metrics features.

- `internal/db/db.go`
  - This package encapsulates persistence and is architecturally important because the project explicitly uses two databases for different concerns.
  - Per the README:
    - MySQL stores usage metrics and scheduling data.
    - PostgreSQL stores the WhatsApp session.
  - That split matters: app-level operational data is separated from the bot’s durable identity/session state.

The presentation layer is split into static pages and frontend assets:

- `public/`
  - Contains the user-facing dashboard pages: `index.html`, `login.html`, `chat.html`, `connect.html`, `messages.html`, `api-keys.html`.
  - `public/js/app.js` is the client-side coordinator that calls the backend endpoints and updates the UI.
  - This looks like a multi-page static dashboard rather than a SPA framework app.

- `ui/`
  - Contains HTML source files under `ui/live_chat_web_style/` and `ui/login_page/`.
  - These appear to be design/source assets for the dashboard pages, possibly used to generate or maintain the HTML in `public/`.

The main data flows are:

1. A user opens the dashboard pages from `public/`.
2. Browser JavaScript in `public/js/app.js` calls the Go API for status, QR login, messaging, metrics, and connection control.
3. `internal/api` authenticates the request through `internal/auth`, then invokes `internal/bot` or `internal/db`.
4. The bot layer communicates with WhatsApp through `whatsmeow`.
5. Message events and connection state can flow back out through `/ws/bridge` to remote consumers such as Laravel.
6. Scheduled and bulk sends are persisted and later executed by the scheduler against the bot.
7. The monitor watches the WhatsApp connection and reconnects when needed.

External integration points that define the system boundary:

- WhatsApp itself, via `whatsmeow`.
- Remote applications, especially Laravel, which can call `/api/send` or use `/ws/bridge`.
- MySQL and PostgreSQL, each used for a distinct storage responsibility.
- Docker/Koyeb deployment, with the server configured to listen on the platform-provided port.

In diagram terms, the cleanest separation is:
- presentation/UI on the left,
- HTTP/WebSocket API in the middle,
- bot/control/background workers as the core,
- and two persistence stores plus WhatsApp as the external dependencies.

Main entry points: [`internal/api/handlers.go`](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/api/handlers.go) (HTTP API), [`main.go`](https://github.com/hashirbot/whats-bridge/blob/HEAD/main.go) (main.go), [`internal/db/db.go`](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/db/db.go) (Data Access), [`internal/bot/bot.go`](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/bot/bot.go) (Bot Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Entrypoint"
  main["main.go<br/>entrypoint<br/>[main.go]"]
end

subgraph "Presentation"
  dashboard["Dashboard<br/>static UI<br/>[index.html]"]
  clientjs["Client JS<br/>browser script<br/>[app.js]"]
  uiassets["UI Assets<br/>page sources<br/>[code.html]"]
end

subgraph "API Layer"
  api["HTTP API<br/>handler layer<br/>[handlers.go]"]
  auth["Auth<br/>access control<br/>[auth.go]"]
end

subgraph "Core Service"
  bot["Bot Core<br/>whatsapp service<br/>[bot.go]"]
  bridge["WS Bridge<br/>realtime relay<br/>[bridge.go]"]
  monitor["Monitor<br/>watchdog<br/>[monitor.go]"]
  scheduler["Scheduler<br/>dispatch worker<br/>[scheduler.go]"]
end

subgraph "Persistence"
  db["Data Access<br/>persistence layer<br/>[db.go]"]
  mysql[("MySQL<br/>metrics store")]
  postgres[("PostgreSQL<br/>session store")]
end

whatsapp(("WhatsApp<br/>external platform"))
browser(("Browser User<br/>client"))
apps(("External Apps<br/>integration client"))

main -->|"wires"| api
main -->|"initializes"| bot
main -->|"connects"| db
main -->|"starts"| monitor
main -->|"starts"| scheduler
browser -->|"loads"| dashboard
browser -->|"runs"| clientjs
clientjs -->|"calls"| api
api -->|"checks"| auth
api -->|"delegates"| bot
api -->|"persists"| db
api -->|"exposes"| bridge
bridge -->|"streams to"| apps
bot -->|"connects"| whatsapp
monitor -->|"watches"| bot
scheduler -->|"reads jobs"| db
scheduler -->|"dispatches"| bot
db -->|"uses"| mysql
db -->|"uses"| postgres
uiassets -.->|"shapes"| dashboard

click main "https://github.com/hashirbot/whats-bridge/blob/main/main.go"
click dashboard "https://github.com/hashirbot/whats-bridge/blob/main/public/index.html"
click clientjs "https://github.com/hashirbot/whats-bridge/blob/main/public/js/app.js"
click uiassets "https://github.com/hashirbot/whats-bridge/blob/main/ui/live_chat_web_style/code.html"
click api "https://github.com/hashirbot/whats-bridge/blob/main/internal/api/handlers.go"
click auth "https://github.com/hashirbot/whats-bridge/blob/main/internal/auth/auth.go"
click bot "https://github.com/hashirbot/whats-bridge/blob/main/internal/bot/bot.go"
click bridge "https://github.com/hashirbot/whats-bridge/blob/main/internal/bot/bridge.go"
click monitor "https://github.com/hashirbot/whats-bridge/blob/main/internal/bot/monitor.go"
click scheduler "https://github.com/hashirbot/whats-bridge/blob/main/internal/bot/scheduler.go"
click db "https://github.com/hashirbot/whats-bridge/blob/main/internal/db/db.go"

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 main toneBlue
class dashboard,clientjs,uiassets toneAmber
class api,auth toneMint
class bot,bridge,monitor,scheduler toneRose
class db,mysql,postgres toneIndigo
class whatsapp,browser,apps toneNeutral
```

## Components

### Entrypoint

Application startup and wiring

- [main.go](https://github.com/hashirbot/whats-bridge/blob/HEAD/main.go): entrypoint · Bootstraps the service and starts listeners · `main.go`

### Presentation

Static dashboard and front-end assets

- [Dashboard](https://github.com/hashirbot/whats-bridge/blob/HEAD/public/index.html): static UI · User-facing HTML pages · `public/index.html`
- [Client JS](https://github.com/hashirbot/whats-bridge/blob/HEAD/public/js/app.js): browser script · Browser-side API coordinator · `public/js/app.js`
- [UI Assets](https://github.com/hashirbot/whats-bridge/blob/HEAD/ui/live_chat_web_style/code.html): page sources · HTML source assets for dashboard pages · `ui/live_chat_web_style/code.html`

### API Layer

HTTP and WebSocket boundary

- [HTTP API](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/api/handlers.go): handler layer · Routes dashboard and integration requests · `internal/api/handlers.go`
- [Auth](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/auth/auth.go): access control · Checks dashboard and API access · `internal/auth/auth.go`

### Core Service

WhatsApp control and background workflows

- [Bot Core](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/bot/bot.go): whatsapp service · Owns WhatsApp client lifecycle and messaging · `internal/bot/bot.go`
- [WS Bridge](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/bot/bridge.go): realtime relay · Streams events between WhatsApp and external consumers · `internal/bot/bridge.go`
- [Monitor](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/bot/monitor.go): watchdog · Detects disconnects and reconnects · `internal/bot/monitor.go`
- [Scheduler](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/bot/scheduler.go): dispatch worker · Handles deferred and bulk message sending · `internal/bot/scheduler.go`

### Persistence

Storage backends and data access

- [Data Access](https://github.com/hashirbot/whats-bridge/blob/HEAD/internal/db/db.go): persistence layer · Encapsulates database operations · `internal/db/db.go`
- **MySQL**: metrics store · Stores usage metrics and scheduled work
- **PostgreSQL**: session store · Stores WhatsApp session state

### Other components

- **WhatsApp**: external platform · Messaging network via whatsmeow
- **Browser User**: client · Uses dashboard pages and API controls
- **External Apps**: integration client · Remote systems using API or WebSocket bridge

## Connections

- main.go → HTTP API: wires · Starts HTTP and WebSocket handling
- main.go → Bot Core: initializes · Creates the WhatsApp service
- main.go → Data Access: connects · Opens persistence layer
- main.go → Monitor: starts · Launches connection watchdog
- main.go → Scheduler: starts · Launches deferred send worker
- Browser User → Dashboard: loads · Opens dashboard pages
- Browser User → Client JS: runs · Executes browser-side coordinator
- Client JS → HTTP API: calls · Requests status, send, metrics, and control endpoints
- HTTP API → Auth: checks · Applies access control before actions
- HTTP API → Bot Core: delegates · Sends messages and controls connection
- HTTP API → Data Access: persists · Reads and writes scheduling and metrics data
- HTTP API → WS Bridge: exposes · Serves realtime bridge endpoint
- WS Bridge → External Apps: streams to · Shares message and connection events
- Bot Core → WhatsApp: connects · Uses whatsmeow to talk to WhatsApp
- Monitor → Bot Core: watches · Restores lost connectivity
- Scheduler → Data Access: reads jobs · Fetches scheduled and bulk sends
- Scheduler → Bot Core: dispatches · Hands queued messages to the bot
- Data Access → MySQL: uses · Stores operational metrics and schedules
- Data Access → PostgreSQL: uses · Stores WhatsApp session state
- UI Assets → Dashboard: shapes · Source assets for the static pages
