# flowiseai/flowisechatembed architecture

> Architecture diagram of the GitHub repository flowiseai/flowisechatembed, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flowiseai/flowisechatembed
- Repository: https://github.com/flowiseai/flowisechatembed

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef host fill:#dddddd,stroke:#888888,color:#000000
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000000
    classDef network fill:#d5f5e3,stroke:#27ae60,color:#000000
    classDef external fill:#fdebd0,stroke:#e67e22,color:#000000
    classDef build fill:#f2f2f2,stroke:#aaaaaa,color:#000000

    %% Host Page
    HostPage["Host Web Page\npublic/index.html"]:::host
    click HostPage "https://github.com/flowiseai/flowisechatembed/blob/main/public/index.html"

    %% Build Pipeline
    subgraph "Build Pipeline" 
        Rollup["rollup.config.js"]:::build
        DistJS["dist/web.js\nweb.umd.js"]:::build
        DistTypes["dist/types/*.d.ts"]:::build
        click Rollup "https://github.com/flowiseai/flowisechatembed/blob/main/rollup.config.js"
        click DistJS "https://github.com/flowiseai/flowisechatembed/blob/main/dist/web.js"
    end

    %% Client-Side Embed
    subgraph "Client Embed Widget" 
        WebJS["Embed Script Loader\nweb.js / web.umd.js"]:::client
        click WebJS "https://github.com/flowiseai/flowisechatembed/blob/main/dist/web.js"
        subgraph "Entry Points"
            Register["register.tsx"]:::client
            click Register "https://github.com/flowiseai/flowisechatembed/blob/main/src/register.tsx"
            WebTS["web.ts"]:::client
            click WebTS "https://github.com/flowiseai/flowisechatembed/blob/main/src/web.ts"
            Index["index.ts"]:::client
            click Index "https://github.com/flowiseai/flowisechatembed/blob/main/src/index.ts"
        end
        subgraph "React UI Components"
            Badge["Badge.tsx"]:::client
            click Badge "https://github.com/flowiseai/flowisechatembed/blob/main/src/components/Badge.tsx"
            Bot["Bot.tsx"]:::client
            click Bot "https://github.com/flowiseai/flowisechatembed/blob/main/src/components/Bot.tsx"
            Typing["TypingBubble.tsx"]:::client
            click Typing "https://github.com/flowiseai/flowisechatembed/blob/main/src/components/TypingBubble.tsx"
            Avatars["avatars/*.tsx"]:::client
            click Avatars "https://github.com/flowiseai/flowisechatembed/blob/main/src/components/avatars/Avatar.tsx"
            Bubbles["bubbles/*.tsx"]:::client
            click Bubbles "https://github.com/flowiseai/flowisechatembed/tree/main/src/components/bubbles"
            Buttons["buttons/*.tsx"]:::client
            click Buttons "https://github.com/flowiseai/flowisechatembed/tree/main/src/components/buttons"
            Icons["icons/*.tsx"]:::client
            click Icons "https://github.com/flowiseai/flowisechatembed/tree/main/src/components/icons"
            Inputs["inputs/textInput/*.tsx"]:::client
            click Inputs "https://github.com/flowiseai/flowisechatembed/tree/main/src/components/inputs/textInput"
            Treeview["treeview Components"]:::client
            click Treeview "https://github.com/flowiseai/flowisechatembed/blob/main/src/components/treeview/TreeView.tsx"
        end
        subgraph "Features & Modes"
            BubbleFeature["bubble/index.ts"]:::client
            click BubbleFeature "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/bubble/index.ts"
            BubbleComp["Bubble.tsx + Tooltip"]:::client
            click BubbleComp "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/bubble/components/Bubble.tsx"
            FullFeature["full/index.ts"]:::client
            click FullFeature "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/full/index.ts"
            FullComp["Full.tsx"]:::client
            click FullComp "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/full/components/Full.tsx"
            PopupFeature["popup/index.ts"]:::client
            click PopupFeature "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/popup/index.ts"
            PopupComp["Popup.tsx"]:::client
            click PopupComp "https://github.com/flowiseai/flowisechatembed/blob/main/src/features/popup/components/Popup.tsx"
        end
        subgraph "Networking Layer"
            SendQuery["sendMessageQuery.ts"]:::network
            click SendQuery "https://github.com/flowiseai/flowisechatembed/blob/main/src/queries/sendMessageQuery.ts"
        end
        subgraph "Utilities"
            EmbedUtil["embedScript.js"]:::client
            click EmbedUtil "https://github.com/flowiseai/flowisechatembed/blob/main/src/utils/embedScript.js"
            AudioUtil["audioRecording.ts"]:::client
            click AudioUtil "https://github.com/flowiseai/flowisechatembed/blob/main/src/utils/audioRecording.ts"
            HistoryUtil["chatInputHistory.ts"]:::client
            click HistoryUtil "https://github.com/flowiseai/flowisechatembed/blob/main/src/utils/chatInputHistory.ts"
            MobileUtil["isMobileSignal.ts"]:::client
            click MobileUtil "https://github.com/flowiseai/flowisechatembed/blob/main/src/utils/isMobileSignal.ts"
            UtilsIndex["utils/index.ts"]:::client
            click UtilsIndex "https://github.com/flowiseai/flowisechatembed/blob/main/src/utils/index.ts"
        end
    end

    %% Proxy Server
    subgraph "Proxy Server (Optional)" 
        Env[".env.example"]:::network
        click Env "https://github.com/flowiseai/flowisechatembed/blob/main/.env.example"
        ServerJS["server.js"]:::network
        click ServerJS "https://github.com/flowiseai/flowisechatembed/blob/main/server.js"
    end

    %% External Flowise API
    FlowiseAPI["Flowise Backend\n(apiHost)"]:::external

    %% Data Flow
    HostPage -->|"loads"| WebJS
    WebJS -->|"bootstraps"| Register
    Register --> WebTS
    Register --> Index
    Index --> Badge
    Index --> Bot
    Index --> SendQuery
    SendQuery -->|"POST /message"| ProxyServer{Proxy Enabled?}
    ProxyServer -->|"validate & forward"| FlowiseAPI
    SendQuery -->|"POST /message"| FlowiseAPI
    FlowiseAPI -->|"response"| ProxyServer
    FlowiseAPI -->|"response"| SendQuery
    ProxyServer --> SendQuery
    SendQuery -->|"data"| Bot
    Bot -->|"renders"| HostPage
    Bot -->|"observer callbacks"| HostPage

    %% Build Relations
    Rollup --> DistJS
    Rollup --> DistTypes
    DistJS --> WebJS

    %% Proxy relations
    SendQuery -.-> ProxyServer
    ProxyServer -.-> FlowiseAPI

    class HostPage host
    class Rollup,DistJS,DistTypes build
    class WebJS,Register,WebTS,Index,Badge,Bot,Typing,Avatars,Bubbles,Buttons,Icons,Inputs,Treeview,BubbleFeature,BubbleComp,FullFeature,FullComp,PopupFeature,PopupComp,EmbedUtil,AudioUtil,HistoryUtil,MobileUtil,UtilsIndex client
    class SendQuery,ServerJS,Env network
    class FlowiseAPI external
```
