How flowiseai/flowisechatembed works
Project Type & Purpose
• This repository is a full-stack JavaScript library (Flowise-Embed) that provides:
• A client-side React/TypeScript widget (pop-up or full-page) for embedding a Flowise chatbot into any website.
• An optional Node.js proxy server to securely relay requests to a Flowise backend without exposing API keys or chatflow IDs.
Top-Level File Structure & Architectural Patterns
• src/
• queries/sendMessageQuery.ts: GraphQL/REST query abstraction to communicate with Flowise API.
• utils/: client-side helpers (audio recording, history, embedScript).
• register.tsx + web.ts + index.ts: Entry-points that bootstrap the widget, register custom elements, and expose init/initFull.
• public/index.html: Test harness for dev server (Vite) showing how the widget is embedded.
• server.js + .env.example: Express-based proxy server to handle domain whitelisting, API key injection, and secure forwarding to Flowise.
• rollup.config.js: Bundles src into ESM (web.js) and UMD (web.umd.js) for npm distribution under dist/.
• dist/: Compiled JavaScript (web.js, web.umd.js) and TypeScript declarations for end-users.
Key Architectural Components
a. Host Web Page
• Any consumer’s website that includes <script type="module" src="…/web.js"> and calls Chatbot.init(...) or Chatbot.initFull(...).
b. Client Embed Widget
• React components (buttons, bubbles, dialogs) rendered into a shadow DOM or a custom <flowise-fullchatbot> element.
• Configuration API (chatflowConfig, theme, observersConfig).
• Uses utils/embedScript.js to inject CSS/HTML and orchestrate lifecycle.
c. Networking Layer
• sendMessageQuery: Delegates message send/receive via fetch to apiHost (Flowise instance or proxy).
• Observers: Hooks for parent page to monitor input, loading, and message streams.
d. Proxy Server (optional)
• An Express app (server.js) that:
• Reads .env to map identifiers → chatflow IDs + allowed domains.
• Implements domain check, API key injection, and forwarding to Flowise API.
• Protects client from exposing sensitive endpoints and enforces CORS/ACL.
e. Flowise Backend (external)
• The actual LLM/chat orchestration server, addressed via apiHost. Could be direct or via proxy.
Relationships & Data Flow
1. Host page loads web.js → Chatbot.init(…)
2. Widget mounts UI (React)
3. User types message → sendMessageQuery → HTTP POST to apiHost
4. If proxy enabled: request → Proxy Server → validates domain & identifier → forwards to Flowise API.
5. Flowise responds with bot message stack → Proxy (if present) → client widget
6. Widget renders responses, triggers observer callbacks
Architectural Patterns & Design Principles
• Component-based UI (React) with thematic customization via props.
• Separation of concerns: UI vs. networking layer vs. configuration.
• Pluggable proxy layer to isolate security concerns.
• CI/CD–style build pipeline: Rollup for bundling, TS declarations for consumers.
• Shadow DOM / Custom Elements for encapsulation (full-page mode).
Elements
• Clear labels for: Host Page, Embed Script (web.js), React UI Components, Networking Layer, Proxy Server, Flowise API
• Annotation of configuration flows: .env → Proxy, init options → Widget theming & behavior