The Problem

Teams building WhatsApp Business or Instagram messaging products need a self-hostable, multi-tenant chat UI without paying per-seat SaaS fees. Most open-source options are single-tenant or tightly coupled to a specific backend. OpenBSP UI solves this by providing a complete React frontend designed to work with the companion OpenBSP API, giving you a white-label interface for conversations, contacts, and AI agent management.

What This Does

OpenBSP UI is a Vite + React + TypeScript single-page application. It implements a WhatsApp-style chat interface with real-time updates, media handling (images, audio, documents), message status indicators, and inline template sending. The app also covers contacts management, AI agent configuration, WhatsApp template building, and multi-organization administration.

The codebase is organized into src/routes/ (TanStack Router file-based routing), src/components/ (UI components), src/queries/ (TanStack Query hooks), src/stores/ (Zustand state), and src/supabase/ (client and type definitions). The entry point is src/main.tsx, with the auth-gated layout in src/routes/_auth.tsx.

How It Is Wired

Execution starts at index.html → src/main.tsx, which mounts the TanStack Router with the route tree generated in src/routeTree.gen.ts. This file is the most connected module in the import graph (54 imports) and carries high instability (0.98) — any change ripples widely. The auth layout src/routes/_auth.tsx gates all authenticated routes, which then branch into conversations, contacts, agents, integrations, and settings.

Data flows through src/queries/ hooks, which are the hub of the application. src/queries/queryKeys.ts is depended on by 12 modules and is the single point of cache-key management — high blast radius, keep it stable. The src/supabase/client.ts module (instability 0.91) is the gateway to the external Supabase backend; it's imported by only one module but itself imports 10, making it a choke point for all database access.

A notable structural issue: src/components/Message/Message.tsx participates in a circular import cycle with DocumentMessage.tsx and src/stores/uiSlice.ts. This makes the message rendering path harder to refactor and increases the risk of subtle initialization bugs.

How To Use It

Setup: npm install from the repository root (package-lock.json is present).

Configuration: Copy .env.example to .env and set:

  • VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY (required)
  • VITE_META_APP_ID (optional, for WhatsApp Embedded Signup)
  • VITE_FB_LOGIN_CONFIG_ID (optional, for Tech Provider flow)

Running: npm run dev for local development. Build with npm run build; output goes to dist/ for static hosting (Cloudflare Pages is documented in the README).

Real-World Use

A typical deployment: host the SPA on Cloudflare Pages, point it at a Supabase project, and have the OpenBSP API handle the WhatsApp Business API integration. An agent configured via src/routes/_auth/agents/new.tsx can then respond to inbound WhatsApp messages in real-time, using templates built in the TemplateEditor component. The multi-org support (src/stores/chatSlice.ts, src/queries/useOrganizations.ts) lets you run one instance for multiple client accounts.

Code Health & Issues

Static analysis (not opinion) found 31 issues across 8 categories:

  • High — 4 oversized files: src/supabase/db_types.ts (1901 lines), src/components/ToolsSection.tsx, src/routeTree.gen.ts. Hard to hold in one head; split by responsibility.
  • High — 7 import cycle members: src/components/Message/Message.tsx, DocumentMessage.tsx, src/stores/uiSlice.ts. Extract shared types or invert dependencies.
  • High — 540 duplicated 6-line code blocks across 61 files (e.g., ChatFooter.tsx, TemplatePreview.tsx). DRY the repeated logic.
  • Medium — 12 deeply nested files (max indentation depth 6) and 3 high-branching files (ChatListItem.tsx: 138 branches over 381 lines).
  • Low — 10 TODO/FIXME markers across FilePreviewer.tsx, AudioMessage.tsx, and whatsapp_template_types.ts.

SDLC observations: no test suite exists (151 source files, zero tests), which is the single highest-risk gap. CI exists but lacks least-privilege token permissions, Dependabot/Renovate, dependency scanning, and job timeouts. No secrets committed; license and lockfile present.

The Bottom Line

A functional, feature-complete WhatsApp/Instagram UI with solid architecture patterns (TanStack Query, Zustand, typed Supabase). The lack of tests and the import cycles are the main technical debts. Suitable for teams already using Supabase and the OpenBSP API who want a customizable frontend without building from scratch.