Free, Open Source, Self-Hosted WhatsApp API Gateway
17 - Dashboard Design
17.1 Overview
The dashboard is a web-based management interface for OpenWA that lets users manage sessions, webhooks, and monitor activity without using the API directly.
Tech Stack
flowchart LR
subgraph Frontend
REACT[React 19]
VITE[Vite 8]
TS[TypeScript]
CSS[Hand-written per-page CSS]
LUCIDE[lucide-react Icons]
end
subgraph State
TANSTACK[TanStack Query]
CTX[React Context]
end
subgraph Backend
API[OpenWA API]
WS[socket.io WebSocket]
end
Frontend --> State
State --> Backend
The styling foundation is plain CSS — there is no Tailwind, no shadcn/ui, and no CSS-in-JS.
Every page — and most shared components — ships its own stylesheet colocated beside the source
(Sessions.tsx + Sessions.css, Layout.tsx + Layout.css, ...), imported directly by the
component (see §17.4 for the handful that carry no stylesheet of their own). Icons come from
lucide-react; charts from recharts; i18n from react-i18next.
Client state is TanStack Query for most server data (see src/hooks/queries.ts; §17.5 names the
pages that keep their own copy) plus three small React
Context providers (RoleProvider, ToastProvider, NumberCheckProvider); theme mode is a provider-less useTheme hook
backed by localStorage — there is no Zustand store.
Design Principles
- Minimalist - Clean, uncluttered interface
- Responsive - Works on desktop and mobile
- Real-time - Live updates via WebSocket
- Accessible - built to WCAG 2.1 AA as the target. Shipped: full keyboard reachability of
the chat/channel/status lists (role, focus, Enter/Space activation), focus-visible styling, the
form labels in the settings and config surfaces associated with their controls via
htmlFor/id, toggle switches and button groups that expose an accessible name and their selected state, and a muted-text token that meets AA on both themes.dashboard/src/a11y-controls.test.tsfails the build when a toggle switch, a button toggle-group or a plugin config field loses its name; other control shapes are not covered by it. Brand and status colours are split in two:--primary,--error,--successand--warningare fill colours for buttons, borders and tints, and--primary-text,--error-text,--success-textand--warning-textare darkened twins for anything rendered as text or an icon. As foregrounds the originals measure 1.98:1, 3.76:1, 2.28:1 and 2.15:1 on white. Each twin is set from the darkest surface it actually lands on, which is the 10 to 22 percent tint of its own hue that the badges and callouts paint behind it, not white. Dark restates primary, success and warning as the originals, which are 6:1 or better on the dark surfaces, and lightens error to#f77b7b, which clears 4.65:1 on the 20 percent error tint over Slate 800, because the original measures 3.89:1 on Slate 800 (#1e293b), the dark card surface. Known gap: the exclusive button groups reportaria-pressedwithout arrow-key roving focus. Every page has a render test, but only Infrastructure's resolves the caption references against a real DOM; elsewhere they are checked structurally. Treat the claim as directional, not certified. - Dark mode - Support for light/dark themes
17.2 Information Architecture
The dashboard is a flat, single-level route table (see src/App.tsx). Each sidebar entry maps
to one top-level page — there are no nested detail/:id routes; a session or chat is opened in-place
(modals / split panes) rather than via its own URL.
flowchart TB
subgraph "Always visible"
HOME[Dashboard /]
SESSIONS[Sessions /sessions]
CHATS[Chats /chats]
NUMBERS[Number Checker /number-checker]
WEBHOOKS[Webhooks /webhooks]
TEMPLATES[Templates /templates]
TESTER[Message Tester /message-tester]
end
subgraph "Admin-only"
APIKEYS[API Keys /api-keys]
INFRA[Infrastructure /infrastructure]
PLUGINS[Plugins /plugins]
LOGS[Logs /logs]
end
HOME --> SESSIONS
HOME --> CHATS
SESSIONS --> CHATS
Navigation Structure
The route table lives in src/App.tsx; the sidebar items in src/components/Layout.tsx. Routes
guarded by role === 'admin' are only mounted (and only shown in the sidebar) for an admin key —
a non-admin hitting the path falls through to the * redirect. API Keys, Infrastructure and Plugins
also need a key not restricted to selected sessions (role === 'admin' && !scoped, with scoped
from POST /api/auth/validate), because their routes refuse a session-scoped key; /logs is
mounted for any admin key.
/ → Dashboard (overview + charts)
/sessions → Sessions (create / start / stop / QR / delete)
/chats → Chats (full height, no page header; session switcher listing every session;
Chats / Channels / Status tabs, quick filters and an Archived view on Chats;
chat list + message thread live via WebSocket; thread pages older history in
on scroll-up; per-chat menu (pin, mute, archive, mark unread, block, leave
group, clear, delete) [operator]; contact info
panel and group info dialog; new chat / new group [operator]; read-only
channel feed on whatsapp-web.js)
/number-checker → Number Checker (single and bulk check of whether numbers are on WhatsApp) [operator]
/webhooks → Webhooks (per-session webhook endpoints)
/templates → Message Templates
/message-tester → Message Tester (ad-hoc send-* + check-number)
/logs → Activity / Audit Logs [admin only]
/api-keys → API Keys Management [admin, unscoped key only]
/infrastructure → Infrastructure status & config [admin, unscoped key only]
/plugins → Plugins (install / enable / configure) [admin, unscoped key only]
* → redirect to /
There is no Settings page and no
/sessions/:id,/sessions/:id/chat, or/webhooks/:idroute. Theme (light/dark/system) is a one-click toggle in the sidebar footer (Layout.tsx), persisted client-side by theuseThemehook. The button that collapses the sidebar to its icon rail sits in the sidebar header, beside the logo, and under the logo once collapsed; its panel icon is mirrored for right-to-left languages.
17.3 Wireframes
Dashboard Home
┌─────────────────────────────────────────────────────────────────────┐
│ 🔵 OpenWA 🔍 Search 👤 Admin ☀️ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│ │ 📱 5 │ ✅ 4 │ 📨 1,234 │ 🔗 3 │ │
│ │ Sessions │ Connected │ Messages │ Webhooks │ │
│ │ │ │ (Today) │ Active │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
│ │
│ ┌──────────────────────────────────┐ ┌────────────────────────┐ │
│ │ Sessions Overview │ │ Recent Activity │ │
│ │ ┌──────┬──────┬──────┬──────┐ │ │ │ │
│ │ │ 🟢 │ 🟢 │ 🟢 │ 🟡 │ │ │ 10:30 Message sent │ │
│ │ │ CS-1 │ CS-2 │ Sales│ Supp │ │ │ 10:28 Webhook called │ │
│ │ │ 123 │ 456 │ 789 │ - │ │ │ 10:25 Session online │ │
│ │ └──────┴──────┴──────┴──────┘ │ │ 10:20 Message recv │ │
│ │ │ │ 10:15 QR scanned │ │
│ │ [+ New Session] │ │ │ │
│ └──────────────────────────────────┘ │ [View All →] │ │
│ └────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Message Volume (Last 7 Days) │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ ▓▓ │ │ │
│ │ │ ▓▓ ▓▓ ▓▓ │ │ │
│ │ │ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ │ │ │
│ │ │ ▓▓▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ │ │ │
│ │ │ Mon Tue Wed Thu Fri Sat Sun │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Session List
┌─────────────────────────────────────────────────────────────────────┐
│ ← Sessions [+ New Session] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🔍 Search sessions... Filter: [All ▾] [Status ▾] │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ ● Customer Support 1 🟢 Connected │ │
│ │ 📱 +62 812-3456-789 │ │
│ │ 📨 1,234 messages | Last active: 2 min ago │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │ [📷 QR] [💬 Test Chat] [⚙️ Settings] [🗑️ Delete] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ ● Sales Bot 🟢 Connected │ │
│ │ 📱 +62 821-9876-543 │ │
│ │ 📨 567 messages | Last active: 5 min ago │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │ [📷 QR] [💬 Test Chat] [⚙️ Settings] [🗑️ Delete] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ ○ Support Backup 🟡 Disconnected │ │
│ │ 📱 Not connected │ │
│ │ 📨 0 messages | Never active │ │
│ │ ─────────────────────────────────────────────────────────── │ │
│ │ [📷 Scan QR] [⚙️ Settings] [🗑️ Delete] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ──────────────────────────────────────────────────────────────── │
│ Showing 3 of 3 sessions [◀] 1 [▶] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Session Detail
┌─────────────────────────────────────────────────────────────────────┐
│ ← Sessions / Customer Support 1 🟢 Connected │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ ┌─────────┐ │ │
│ │ │ 👤 │ Customer Support 1 │ │
│ │ │ Avatar │ +62 812-3456-789 │ │
│ │ │ │ Status: 🟢 Connected │ │
│ │ └─────────┘ Platform: Android │ │
│ │ │ │
│ │ [Restart Session] [Unlink Device] [Delete] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Unlink Device attempts an engine-native unlink of this companion │
│ device (POST /sessions/:sessionId/logout), then stops the │
│ session. A 200 means the unlink + local cleanup completed (not an │
│ independent Linked-Devices observation) — reconnecting then │
│ requires a fresh QR scan or pairing code. A 502 │
│ (SESSION_LOGOUT_INCOMPLETE) stops locally but leaves the │
│ operation incomplete; retry after starting. Delete only clears │
│ the local data; it does NOT unlink. │
│ │
│ ┌─────────────────────┬─────────────────────┐ │
│ │ 📊 Statistics │ ⚙️ Configuration │ │
│ ├─────────────────────┼─────────────────────┤ │
│ │ │ │ │
│ │ Messages Sent │ Auto Reconnect │ │
│ │ ████████░░ 1,234 │ [✓] Enabled │ │
│ │ │ │ │
│ │ Messages Received │ Webhook URL │ │
│ │ ██████████ 2,567 │ https://... │ │
│ │ │ │ │
│ │ Webhook Calls │ Proxy │ │
│ │ ███████░░░ 890 │ None │ │
│ │ │ │ │
│ │ Uptime │ Created │ │
│ │ 99.9% (30 days) │ 2026-01-15 │ │
│ │ │ │ │
│ └─────────────────────┴─────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Recent Messages [View All →] │ │
│ │ ───────────────────────────────────────────────────────── │ │
│ │ → +62 821... | Hello, how can I help? | 10:30 ✓✓ │ │
│ │ ← +62 821... | I need product info | 10:28 │ │
│ │ → +62 821... | Sure! Here's our catalog | 10:25 ✓✓ │ │
│ │ ← +62 813... | Thanks for your help! | 10:20 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ [💬 Open Test Chat] │
│ │
└─────────────────────────────────────────────────────────────────────┘
QR Code Scanner
┌─────────────────────────────────────────────────────────────────────┐
│ Scan QR Code │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ │
│ │ │ │
│ │ ████████████████████ │ │
│ │ ██ ████ │ │
│ │ ██ ██████████ ████ │ │
│ │ ██ ██ ██ ████ │ │
│ │ ██ ██ ██ ████ │ │
│ │ ██ ██ ██ ████ │ │
│ │ ██ ██████████ ████ │ │
│ │ ██ ████ │ │
│ │ ████████████████████ │ │
│ │ │ │
│ └─────────────────────────┘ │
│ │
│ Expires in: 0:45 │
│ │
│ ────────────────────────────────────────────────────── │
│ │
│ 1. Open WhatsApp on your phone │
│ 2. Tap Menu ⋮ or Settings ⚙ │
│ 3. Tap Linked Devices │
│ 4. Tap Link a Device │
│ 5. Point your phone at this screen │
│ │
│ ────────────────────────────────────────────────────── │
│ │
│ [Refresh QR] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────────────┘
Test Chat Interface
┌─────────────────────────────────────────────────────────────────────┐
│ ← Test Chat Session: Customer Support │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────┐ ┌────────────────────────────────────┐ │
│ │ Contacts │ │ +62 821-9876-543 │ │
│ │ ────────────────── │ │ John Doe │ │
│ │ │ ├────────────────────────────────────┤ │
│ │ 🔍 Search... │ │ │ │
│ │ │ │ ┌──────────────────────────────┐ │ │
│ │ ┌────────────────┐ │ │ │ Hello! How can I help you? │ │ │
│ │ │ 👤 John Doe │ │ │ │ 10:30 ✓✓ │ │ │
│ │ │ Last: Hi! │ │ │ └──────────────────────────────┘ │ │
│ │ └────────────────┘ │ │ │ │
│ │ │ │ ┌─────────────────────────┐ │ │
│ │ ┌────────────────┐ │ │ │ I need help with my │ │ │
│ │ │ 👤 Jane Smith │ │ │ │ order #12345 │ │ │
│ │ │ Last: OK │ │ │ │ 10:31 │ │ │
│ │ └────────────────┘ │ │ └─────────────────────────┘ │ │
│ │ │ │ │ │
│ │ ┌────────────────┐ │ │ ┌──────────────────────────────┐ │ │
│ │ │ 👤 Bob Wilson │ │ │ │ Sure! Let me check that │ │ │
│ │ │ Last: Thx │ │ │ │ for you. One moment... │ │ │
│ │ └────────────────┘ │ │ │ 10:32 ✓✓ │ │ │
│ │ │ │ └──────────────────────────────┘ │ │
│ │ │ │ │ │
│ │ ────────────────── │ ├────────────────────────────────────┤ │
│ │ [+ New Chat] │ │ 📎 [ ] 📤 │ │
│ └──────────────────────┘ │ Type a message... │ │
│ └────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Webhook Management
┌─────────────────────────────────────────────────────────────────────┐
│ ← Webhooks [+ New Webhook] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 🔗 Main Webhook ✅ Active │ │
│ │ https://api.example.com/webhook/openwa │ │
│ │ Events: message.received, message.ack, session.status │ │
│ │ Sessions: All │ │
│ │ ──────────────────────────────────────────────────────────── │ │
│ │ Success Rate: 99.8% | Avg Latency: 125ms | Last: 2 min ago │ │
│ │ [Test] [View Logs] [Edit] [Disable] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 🔗 Analytics Webhook ✅ Active │ │
│ │ https://analytics.example.com/track │ │
│ │ Events: message.received │ │
│ │ Sessions: cs-1, sales │ │
│ │ ──────────────────────────────────────────────────────────── │ │
│ │ Success Rate: 100% | Avg Latency: 89ms | Last: 5 min ago │ │
│ │ [Test] [View Logs] [Edit] [Disable] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ 🔗 Backup Webhook ⏸️ Disabled │ │
│ │ https://backup.example.com/wa │ │
│ │ Events: message.received, message.ack │ │
│ │ Sessions: All │ │
│ │ ──────────────────────────────────────────────────────────── │ │
│ │ [Enable] [Edit] [Delete] │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
17.4 Component Library
No component framework is installed. shadcn/ui is not adopted — there is no
npx shadcninit, nocomponents/ui/directory, nocn()utility, and no@/componentsimport alias. The wireframes above are design intent; the implementation is hand-written.
Bespoke components
The UI is built from a small set of project-specific components under dashboard/src/components/,
most with a colocated CSS file. Seven top-level components ship none: ErrorBoundary styles inline
via style={{...}}, GithubIcon carries no styling beyond fill="currentColor", Modal reuses the
global .modal-* rules from index.css, GroupPicker and SessionScopePicker are styled by the
one page that uses each (pages/MessageTester.css, pages/ApiKeys.css), and RoleProvider and
NumberCheckProvider render no DOM. Nothing under chats/ ships its own stylesheet either: those
components take their classes from pages/Chats.css, and MediaLightbox adds the
yet-another-react-lightbox vendor CSS. There is no design-system package to pull from.
| Component | File | Responsibility |
|---|---|---|
Layout |
components/Layout.tsx |
App shell: collapsible sidebar nav, mobile drawer, language menu, light/dark/system theme toggle, logout, live version badge |
ToastProvider / useToast |
components/Toast.tsx |
Context-based toast notifications (success/error/warning/info) with de-dup keys |
PageHeader |
components/PageHeader.tsx |
Shared page title / subtitle / badge / actions header |
Modal |
components/Modal.tsx |
Accessible dialog (role="dialog", Escape/overlay close, focus trap + restore); uses the global .modal-* styles |
CustomSelect |
components/CustomSelect.tsx |
Keyboard-navigable select replacement (type-ahead, arrow keys) used by Sessions / Logs / Login |
DashboardCharts |
components/DashboardCharts.tsx |
recharts-based message-volume / activity charts on the Dashboard |
FilterBuilder |
components/FilterBuilder.tsx |
Visual condition builder for webhook event filters |
GlobalSearch |
components/GlobalSearch.tsx |
Debounced message search behind a toggle in the Chats sidebar header, with all-sessions / current-session scope |
PluginInstances |
components/PluginInstances.tsx |
Per-plugin instance list: create / edit / delete and secret regeneration |
ErrorBoundary |
components/ErrorBoundary.tsx |
Top-level React error boundary wrapping the whole app |
GithubIcon |
components/GithubIcon.tsx |
Inline brand SVG |
GroupPicker |
components/GroupPicker.tsx |
Searchable multi-select of a session's groups, used by the Message Tester's multi-group send |
SessionScopePicker |
components/SessionScopePicker.tsx |
Per-key session scope checklist on the API Keys page |
RoleProvider |
components/RoleProvider.tsx |
Context holding the logged-in key's role, read with useRole (canWrite gates write actions) |
NumberCheckProvider |
components/NumberCheckProvider.tsx |
Holds the Number Checker's bulk run and its rows above the routes, so leaving the page does not stop a run; read with useNumberCheck |
Chat-specific pieces live one level down in components/chats/: MessageBody (WhatsApp text
formatting + link detection), ChatThread (bubble list with day separators, including inbound
Baileys prompt buttons that call POST /sessions/:id/messages/click-button), and MediaLightbox
(the media viewer, built on yet-another-react-lightbox). The rest of the room is split the same
way: ChatSidebar, SessionPicker (the session switcher in the sidebar header), NewChatPanel
(new chat, and new group on Baileys), ChatRowMenu (a chat row's actions; chatActionItems lists
them for the row and for the room's menu alike), GroupInfoDialog (a group's name, picture,
description and participants), ChatDialogs (mute and save-contact dialogs), ChatComposer,
ChatAvatar, KindIcon, StatusComposeModal and StatusMedia. Prompt choices arrive on live
message.received as top-level buttons and are also stored in message metadata.buttons so a
reload can re-render them. Clicking still requires the prompt to be in the engine store; an evicted
prompt 404s. A read-only key sees the choices disabled and gets no reply, react or delete actions,
the same as the disabled composer, no message search, no New chat button, and of a chat's actions
only its contact or group info.
The message thread is paged. useChatMessages is a useInfiniteQuery whose cursor is the number
of DB rows fetched so far, not the length of the rendered list — the thread also carries engine
history and drops the duplicates between the two, so its length is not an offset the gateway would
agree with. Reaching the top requests the next page; the reading position is held across the
prepend rather than jumping. Both rules are pure functions with tests: utils/messagePages.ts for
the cursor, shouldFetchOlderMessages in utils/scrollDecision.ts for when to ask.
Pages live under dashboard/src/pages/, each as a *.tsx + *.css pair (e.g. Sessions.tsx +
Sessions.css). Pages are lazy-loaded in App.tsx via React.lazy + Suspense.
A representative bespoke component — the shared page header — shows the actual conventions (plain props, a colocated stylesheet, BEM-ish class names, no utility classes):
// components/PageHeader.tsx
import type { ReactNode } from 'react';
import './PageHeader.css';
interface PageHeaderProps {
title: string;
subtitle?: string;
badge?: ReactNode;
actions?: ReactNode;
}
export function PageHeader({ title, subtitle, badge, actions }: PageHeaderProps) {
return (
<header className="page-header">
<div className="page-header__title-group">
<h1>{title}</h1>
{badge && <span className="page-header__badge">{badge}</span>}
</div>
{actions && <div className="page-header__actions">{actions}</div>}
{subtitle && <p className="page-header__subtitle">{subtitle}</p>}
</header>
);
}
Icons are imported individually from lucide-react; there is no Avatar/Card/Badge primitive
library — those visuals are composed directly with divs and the page's own CSS.
17.5 State Management
There is no Zustand store (and no global client-state library). Most server data is owned by
TanStack Query (@tanstack/react-query); the only other shared state lives in the three React
Context providers in the app — RoleProvider (the authenticated key's role, read through the
useRole hook), ToastProvider (transient notifications) and NumberCheckProvider (the Number
Checker's bulk run and its rows, which outlive the page). Theme mode is deliberately not a
context: useTheme is a plain hook that persists to localStorage and writes one attribute on
<html> (see §17.7).
Three pages keep a server list in local state instead of the query cache:
- Sessions (
Sessions.tsx) holds the session list itself and sequences each read against its own row writes and socket pushes, so an older answer never overwrites a newer row. After each read it applies, it invalidates the['sessions']key prefix so the Dashboard and per-session views refetch. - Chats (
Chats.tsx) reads the sessions directly on mount, and again when a search hit names a session that list lacks. The session switcher lists all of them, but only a ready one can be selected; it followssession.statuspushes through the same live session feed the Sessions page joins (utils/sessionFeedSubscription), so a session that connects or drops changes in place. The page keeps the chat list in local state that socket pushes, sends, marking a chat read and the chat actions (pin, mute, archive, rename) update. - Plugins (
Plugins.tsx) keeps the catalog in local state. It prefetches it silently on mount so installed cards can show an update chip, fetches it again when the Catalog tab opens with an empty list, and reloads it after any install, update or uninstall.
API client — raw payloads, no { data } envelope
The client lives in src/services/api.ts. A single request<T>() helper attaches the X-API-Key
header from sessionStorage, then returns the parsed JSON body as-is — the backend sends the
raw handler payload, so request<Session[]>('/sessions') resolves to a bare Session[], not
{ data: Session[] }. (A 204 No Content resolves to undefined; a 401, or a 403 because the
key's allowedIps refuse this client, clears the stored key and redirects to login, but only when the
stored key is the one the request carried: a late answer for a key since replaced fails like any other
error, and a keyless request answered after sign-out stays silent. Any other 403 leaves the key in
place.) Endpoints are grouped into typed namespaces — sessionApi, webhookApi,
templateApi, apiKeyApi, auditApi, messageApi, infraApi, pluginsApi, statsApi, ...
// src/services/api.ts (abridged)
export const API_BASE_URL = `${(import.meta.env.VITE_API_URL ?? '').replace(/\/+$/, '')}/api`;
async function request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
const apiKey = sessionStorage.getItem('openwa_api_key');
const response = await fetch(`${API_BASE_URL}${endpoint}`, {
...options,
headers: {
'Content-Type': 'application/json',
...(apiKey ? { 'X-API-Key': apiKey } : {}),
...options.headers,
},
});
if (!response.ok) {
const error = await response.json().catch(() => ({}));
throw new Error(error.message || `HTTP ${response.status}`);
}
if (response.status === 204) return undefined as T;
return response.json(); // ← the raw payload, no unwrapping
}
export const sessionApi = {
list: () => request<Session[]>('/sessions'), // bare array
get: (id: string) => request<Session>(`/sessions/${id}`),
create: (name: string) => request<Session>('/sessions', { method: 'POST', body: JSON.stringify({ name }) }),
delete: (id: string) => request<void>(`/sessions/${id}`, { method: 'DELETE' }),
// QR returns a raw { qrCode, status } object — not { qr, expiresAt }, and there is no expiry timer.
getQR: (id: string) => request<{ qrCode: string; status: string }>(`/sessions/${id}/qr`),
};
TanStack Query hooks
Hooks wrap those namespaces in src/hooks/queries.ts — each returns the raw payload directly (no
.data.data). Cache invalidation, not a store, keeps the UI in sync after a mutation.
// src/hooks/queries.ts (abridged)
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { sessionApi, webhookApi } from '../services/api';
export const queryKeys = {
sessions: ['sessions'] as const,
webhooks: ['webhooks'] as const,
// ...
};
export function useSessionsQuery() {
return useQuery({
queryKey: queryKeys.sessions,
queryFn: sessionApi.list, // resolves to Session[] directly
staleTime: 30_000,
});
}
export function useStopSessionMutation() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (id: string) => sessionApi.stop(id),
// A failed stop can still have changed the session, so the list is re-read either way.
onSettled: () => {
void queryClient.invalidateQueries({ queryKey: queryKeys.sessions });
},
});
}
There is no
useSessionQrhook and no 30 srefetchInterval. The Sessions page fetches the current QR imperatively viasessionApi.getQR(), anduseSessionPairingre-reads it withGET /sessions/:id/qrevery 5 s while the QR modal is open and the session isqr_ready; in any other state the poll sends no request, and the modal stays open throughauthenticating. The first code and fresh ones are pushed over the WebSocket (session.qrevents, see §17.6).
17.6 WebSocket Integration
Real-time updates use socket.io (socket.io-client), not a raw browser WebSocket. The hook is
src/hooks/useWebSocket.ts. Key facts:
- Namespace
/events(not/ws). The client connects to<origin>/events, where the origin is that ofVITE_WS_URLwhen set, else that ofVITE_API_URL(so a split-origin build reaches the API), elsewindow.location.origin. A path or trailing slash on either variable is dropped, and a value with no scheme (host:port) is dialled on the page's protocol. - API key via the socket.io
authpayload (and anX-API-Keyheader for proxies), deliberately not in the query string — a key in the handshake URL would leak into access logs /Referer. - Reconnection is socket.io's built-in mechanism —
reconnectionAttempts: 5,reconnectionDelay: 1000— not a hand-rolledsetTimeout(connect, 3000). When all attempts are exhausted the manager firesreconnect_failed; the hook surfaces that asconnectionFailedso the UI can offer a manualreconnect(). - Server → client envelope. Every push arrives as a single
messageevent whose payload is{ type: 'event', timestamp, payload: { event, sessionId, data } }. The hook registers one handler, switches onpayload.event, and fans out to typed callbacks. - Subscriptions are sent with
socket.emit('message', { type: 'subscribe' | 'unsubscribe', ... }).
// src/hooks/useWebSocket.ts (abridged)
import { useEffect, useRef, useCallback, useState } from 'react';
import { io, Socket } from 'socket.io-client';
import { API_ORIGIN } from '../services/api';
import { resolveSocketUrl } from '../utils/urlSecurity';
// The origin of VITE_WS_URL, else of VITE_API_URL, else the page origin.
const SOCKET_URL = resolveSocketUrl(import.meta.env.VITE_WS_URL, API_ORIGIN, window.location.origin);
interface ServerEventEnvelope {
type: string; // 'event'
timestamp: string;
payload?: { event: string; sessionId: string; data: Record<string, unknown> };
}
export function useWebSocket(events: WebSocketEvents = {}) {
const socketRef = useRef<Socket | null>(null);
const [isConnected, setIsConnected] = useState(false);
const [connectionFailed, setConnectionFailed] = useState(false);
const connect = useCallback(() => {
if (socketRef.current?.connected) return;
const apiKey = sessionStorage.getItem('openwa_api_key');
if (!apiKey) return;
socketRef.current = io(`${SOCKET_URL}/events`, {
reconnection: true,
reconnectionAttempts: 5,
reconnectionDelay: 1000,
auth: { apiKey }, // key in the handshake auth, NOT the URL
extraHeaders: { 'X-API-Key': apiKey }, // header copy for proxies
});
socketRef.current.on('connect', () => {
setIsConnected(true);
setConnectionFailed(false);
});
socketRef.current.on('disconnect', () => setIsConnected(false));
socketRef.current.io.on('reconnect_failed', () => setConnectionFailed(true));
}, []);
useEffect(() => {
connect();
const socket = socketRef.current;
const handle = (msg: ServerEventEnvelope) => {
if (!msg || msg.type !== 'event' || !msg.payload) return;
const { event, sessionId, data } = msg.payload;
switch (event) {
case 'session.status':
events.onSessionStatus?.({ sessionId, status: String(data.status), timestamp: msg.timestamp });
break;
case 'session.qr':
events.onQRCode?.({ sessionId, qrCode: String(data.qrCode), timestamp: msg.timestamp });
break;
case 'message.received':
case 'message.sent':
events.onMessage?.({ sessionId, message: data, timestamp: msg.timestamp });
break;
// ...message.ack, message.reaction, message.revoked
}
};
socket?.on('message', handle);
return () => {
socket?.off('message', handle);
};
}, [connect, events]);
return { isConnected, connectionFailed, reconnect, subscribe, unsubscribe };
}
17.7 Theme Configuration
Theming is not shadcn HSL design tokens. It is a plain useTheme hook (src/hooks/useTheme.ts)
that toggles one attribute on <html> and lets the CSS do the rest. The value is persisted to
localStorage under openwa_theme:
- Mode —
light | dark | system.systemremovesdata-themeso aprefers-color-schememedia query in the global CSS takes over; otherwisedata-theme="light|dark"is set explicitly.
The sidebar footer button cycles light → dark → system, its label naming the mode a click
selects; there is no
picker popover and no ThemeProvider context wrapper — it's a hook consumed directly where needed.
An earlier accent-palette picker (seven palettes via data-palette) was removed for
maintainability; the legacy openwa_palette storage key and the attribute are cleaned up on load.
// src/hooks/useTheme.ts (abridged)
export type Theme = 'light' | 'dark' | 'system';
export function useTheme() {
const [theme, setTheme] = useState<Theme>(/* localStorage 'openwa_theme' ?? 'system' */);
useEffect(() => {
const root = document.documentElement;
if (theme === 'system') root.removeAttribute('data-theme');
else root.setAttribute('data-theme', theme);
localStorage.setItem('openwa_theme', theme);
}, [theme]);
return { theme, setTheme /* toggleTheme, resolvedTheme */ };
}
The actual colors live in src/App.css as variables keyed off [data-theme] —
e.g. :root { --bg-light: #f8fafc; } [data-theme='dark'] { --bg-light: #0f172a; } — so
switching mode is a single attribute write with no re-render of the tree. The Chats page adds its
own chat palette (bubbles, wallpaper, avatar tones) as variables scoped to the page in
pages/Chats.css, keyed off the same data-theme attribute and prefers-color-scheme, so it
follows the mode too.
17.8 Build & Deployment
Vite Configuration
The dev server listens on 2886 and proxies /api to the API on 2785. The WebSocket proxy is
on /socket.io (socket.io's transport path) with ws: true — not /ws. There is no @
import alias and no custom manualChunks/Radix vendor split; code-splitting is handled by the
per-page React.lazy imports in App.tsx. The build-time version (__APP_VERSION__) is injected
via define from the root package.json — the file a release bumps — resolved relative to the
config file rather than process.cwd(), because the dashboard is normally built from inside
dashboard/, where a cwd-relative read picks up the release-untouched dashboard/package.json
instead. APP_VERSION in the environment still overrides it.
// vite.config.ts
import { readFileSync } from 'node:fs';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
// Root package.json, resolved from this file — NOT process.cwd().
const { version: pkgVersion } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')) as {
version: string;
};
export default defineConfig({
plugins: [react()],
appType: 'spa', // SPA fallback for client-side routing
define: {
__APP_VERSION__: JSON.stringify(process.env.APP_VERSION || pkgVersion),
__BUILD_TIME__: JSON.stringify(new Date().toISOString()),
},
server: {
port: 2886,
proxy: {
// Trailing slash: a plain '/api' prefix would also proxy the /api-keys SPA route.
'/api/': {
target: 'http://localhost:2785',
changeOrigin: true,
secure: false,
},
// socket.io transport — NOT '/ws'
'/socket.io': {
target: 'http://localhost:2785',
ws: true,
changeOrigin: true,
},
},
},
});
Production Build & Serving
The dashboard has no container of its own. In production the NestJS API serves the bundled
SPA from the same process and port (default 2785) via @nestjs/serve-static, so there is no
nginx image and no separate dashboard service to deploy.
How it fits together:
npm run build:allbuilds the API (dist/) and the dashboard (dashboard/dist/). The rootDockerfiledoes this in its builder stage and copiesdashboard/distinto the runtime image.ServeStaticModuleis registered conditionally insrc/app.module.ts: it only activates whendashboard/dist/index.htmlexists and serves the built assets. Its own SPA fallback is off:configure-app.tsanswers the dashboard documents, with the per-response CSP nonce, for GET paths outside/api,/socket.io,/mcpand/assets, so those keep returning real API/WebSocket responses and the body parsers' own 413 and 400. Opt out withSERVE_DASHBOARD=false.- Run it directly with
npm run prod(build + serve) ornode dist/mainagainst a prebuilt image.
In development the build is absent, so serve-static stays inert and the Vite dev server (port
2886, see above) handles the UI with HMR while proxying /api + /socket.io to the API.
Split-origin hosting is still supported. Same-origin serving is the default, not a lock-in: to
host the dashboard separately (a CDN, an object store, or its own container), build it with the API
origin baked in and deploy dashboard/dist wherever you like:
VITE_API_URL=https://api.example.com npm run build # in dashboard/
dashboard/src/services/api.ts reads VITE_API_URL and calls that origin instead of same-origin
/api. The realtime socket follows the same origin unless VITE_WS_URL overrides it. Set
SERVE_DASHBOARD=false on the API so it stops serving its own copy. Remember to add the dashboard's
origin to CORS_ORIGINS on the API.
For TLS or public exposure of the default single-port setup, terminate at your own reverse proxy
(nginx, Caddy, a cloud load balancer, or a k8s Ingress) in front of the API; see
docs/12-troubleshooting-faq.md for an nginx example.