Frontend Overview¶

The frontend uses a modular architecture with shared components across multiple deployment targets.

Architecture¶

frontend/
├── shared/          # Core shared package (@inboundx/shared)
├── widget/          # Standalone JavaScript widget for websites
├── preprod-ui/      # Pre-production testing interface
├── chrome-plugin/   # Chrome extension
├── backend_ui/      # Backend management interface
├── client-backoffice/ # Client configuration dashboard
└── justfile         # Build and development commands

Packages¶

shared - @inboundx/shared¶

Core shared TypeScript package containing:

Component	Description
Components	React components (RoseWidget, ExpandedChatView, etc.)
Services	API services with adapter support
Adapters	Storage and network adapters for different environments
Utils	Utility functions (color, language, theme, conversation)
Types	Comprehensive TypeScript type definitions
Hooks	Custom React hooks

Standalone JavaScript widget for website integration:

Output: inboundx-widget.js - UMD bundle optimized for embedding
Usage: Can be embedded in any website with simple script tag
Adapters: Uses WebStorageAdapter and FetchNetworkAdapter

preprod-ui¶

Pre-production testing interface built with Vite:

Purpose: Test widget with different client configurations
Features: Client selector, environment switching, live preview
Tech: Vite + React with hot reloading

chrome-plugin¶

Chrome extension using shared components:

Adapters: ChromeStorageAdapter and ChromeNetworkAdapter
Background Script: Handles webhook calls and CORS bypass
Content Script: Injects chat widget into web pages

client-backoffice¶

Client configuration dashboard deployed to Cloudflare Pages:

Purpose: Client management and configuration
Deployment: Cloudflare Pages with branch-based environments

Adapter Pattern¶

The architecture uses adapters to handle different environments:

Storage Adapters¶

Adapter	Use Case	Backend
WebStorageAdapter	Web widgets, preprod-ui	`localStorage`
ChromeStorageAdapter	Chrome extension	`chrome.storage.local`
ConfigurableStorageAdapter	Testing	Dynamic selection

Network Adapters¶

Adapter	Use Case	Method
FetchNetworkAdapter	Web widgets, preprod-ui	Direct `fetch()` API
ChromeNetworkAdapter	Chrome extension	`chrome.runtime.sendMessage()`

Benefits¶

Environment Abstraction: Same code works across deployment targets
CORS Handling: Chrome extension adapter bypasses CORS via background script
Storage Flexibility: Consistent API regardless of storage mechanism
Testing Support: Configurable adapters for comprehensive testing

Communication Architecture¶

Chrome Extension Message Flow¶

Content Script → Background Script → External API → Background Script → Content Script

Key Components:

ChromeNetworkAdapter: Sends messages with tracking IDs
Background Script: Makes HTTP requests (bypasses CORS)
Message Types: toggleWidget, checkSiteSupport, callWebhook

Widget Component → FetchNetworkAdapter → External API → Widget Component

Direct HTTP communication without message passing overhead.

Key Features¶

The widget follows strict sequential initialization:

Phase 0: Pre-Initialization (script load, PostHog, Sentry)
Phase 1: Site Configuration (Supabase client, config load)
Phase 2: Analytics Initialization (PostHog, context setup)
Phase 3: Display Decision (traffic control, URL rules)
Phase 4: Widget Render (services init, UI render)

LocalStorage Structure¶

All data consolidated under single "rose" key:

localStorage.rose = {
  version: 1,
  widget: {
    settings: { logLevel, namedLogLevels },
    analytics: { counters, lastSessionId, offlineQueue }
  },
  preprod?: { config, endpoint, client, iframe }  // Only in preprod-ui
}

Form Detection & Tracking¶

Automatic form detection for conversion tracking:

SuperformStrategy: Webflow Superform multi-step forms
CTAPageFormStrategy: Standard forms on CTA pages
Cross-Subdomain Attribution: Cookie fallback for attribution

Build Outputs¶

Package	Output	Purpose
shared/dist/	TypeScript declarations, JS, CSS	Shared library
widget/dist/	UMD bundle	Website embedding
preprod-ui/dist/	Static files	Firebase hosting
chrome-plugin/dist/	Extension files	Chrome Web Store
client-backoffice/dist/	Static files	Cloudflare Pages

Quick Commands¶

cd frontend

# Installation
just install              # Install all dependencies

# Development
just dev-shared           # Watch shared package
just dev-widget           # Widget development
just dev-preprod          # Pre-production UI
just run-preprod          # Run shared + preprod together

# Building
just build                # Build all packages
just build-chrome         # Build Chrome extension

# Testing
just test                 # Run tests
just type-check           # Type check all projects

See Frontend Setup for detailed setup instructions.