Summary

This document outlines the architecture, implementation, and key decisions behind the embeddable AI Chat + Voice Widget. The goal was to build a portable, customizable, robust, multi‑language assistant that can be embedded on any website with a single line of code. The final solution is a self‑contained JavaScript bundle built with React, TypeScript, and Vite, rendered within a Shadow DOM for full style and DOM encapsulation. Configuration is declarative via a global window object, and the backend is a secure, decoupled API using the Vercel AI SDK with Google Gemini.

High‑level system diagram

+-----------------+        HTTPS         +---------------------------+
|  Host Website   |  <script src=...>   |  CDN (jsDelivr, etc.)     |
|  (any stack)    +--------------------->+  Serves single bundle |
|  window.Agent.. |                      +-------------+-------------+
+--------+--------+                                    |
         |                                             |
         | Injects config                              v
         |                                   +---------+----------+
         |                                   |  Widget (IIFE)    |
         |                                   |  React + TS + Vite|
         |                                   |  Shadow DOM UI    |
         |                                   +---------+----------+
         |                                             |
         |                              fetch /api/chat|
         v                                             v
+--------+--------+                          +---------+----------+
|  End User       |                          |  BFF API (/api)   |
|  (browser)      |<------------------------>|  Auth, CORS, RL   |
+-----------------+           stream         |  LLM adapter      |
                                            +---------+----------+
                                                      |
                                                      v
                                            +---------+----------+
                                            |  LLM (Gemini Flash)  |
                                            +--------------------+

Core Architectural Principles

• Universal embeddability: Deliver as a single-file bundle that works in any host environment.
• Host environment isolation: Avoid global scope pollution and prevent host styles from affecting the widget.
• Separation of concerns: Decouple client UI from server business logic and key management.
• Developer experience and extensibility: Simple configuration API, clear local setup, and modern, well‑supported stack.

Responsibility boundaries

[Host Page]
  - Owns user auth and domain
  - Provides AgentWidgetConfig

[Widget (Client)]
  - Renders UI inside Shadow DOM
  - Manages chat state and streaming UI
  - Never stores secrets

[BFF API]
  - Validates CORS
  - Applies rate limiting
  - Talks to LLM provider

[LLM Provider]
  - Text generation and streaming

Technology Stack and Rationale

• React 18 (frontend): Component model and hooks are ideal for complex, stateful UI like chat.
• TypeScript (language): Strong types for safety, maintainability, and self‑documenting public config (window.AgentWidgetConfig).
• Vite (build): Fast HMR in dev and optimized library mode builds for production IIFE bundles.

AI provider and backend services