How hashirbot/whats-bridge works
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: handlers.go HTTP API · main.go main.go · db.go Data Access · bot.go Bot Core
Components 16
Entrypoint
Application startup and wiring
- main.go · Bootstraps the service and starts listeners
main.go
Presentation
Static dashboard and front-end assets
API Layer
HTTP and WebSocket boundary
Core Service
WhatsApp control and background workflows
- Bot Core · Owns WhatsApp client lifecycle and messaging
internal/bot/bot.go - WS Bridge · Streams events between WhatsApp and external consumers
internal/bot/bridge.go - Monitor · Detects disconnects and reconnects
internal/bot/monitor.go - Scheduler · Handles deferred and bulk message sending
internal/bot/scheduler.go
Persistence
Storage backends and data access
- Data Access · Encapsulates database operations
internal/db/db.go - MySQL · Stores usage metrics and scheduled work
- PostgreSQL · Stores WhatsApp session state
Other components
- WhatsApp · Messaging network via whatsmeow
- Browser User · Uses dashboard pages and API controls
- External Apps · Remote systems using API or WebSocket bridge
Connections 20
- 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