# toi500/toibot architecture

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

- Interactive diagram: https://gitdiagram.com/toi500/toibot
- Repository: https://github.com/toi500/toibot

## Overview

##### Project Type and Purpose
- This is a full-stack web application written in Node.js that serves a static frontend (HTML/CSS/JS) and acts as a secure proxy to a Flowise chatbot API.
- Purpose: provide a customizable, embeddable chatbot widget (ToiBot) that streams AI responses, handles file/image uploads, manages sessions, and preserves chat history.

##### File Structure
- Top-level files:
- package.json / package-lock.json → Node.js dependencies & scripts
- server.js → Express server & API proxy
- .env.example → environment variables for Flowise credentials
- README.md → documentation
- public/ (static assets):
- index.html → main chat interface
- css/ → styling (styles.css, custom.css)
- js/ → client logic (chatbot.js)
- embed/ → embeddable web component (toibot.js, toibot-bridge.js)

##### Key README Insights
- Uses Flowise SDK on the server to forward chat requests (with stream support)
- Implements proxy protection so the client never directly calls the Flowise API
- Features include streaming responses, file/image uploads, follow-up prompts, session and chat-history management, markdown rendering, boxed/fullscreen modes, dynamic configuration.
- Network Architecture:
Client Browser ←→ ToiBot Server (Proxy) ←→ Flowise API

##### Main Components
a. Client Layer
- Browser UI (index.html + chatbot.js + styles.css)
- Embed Component (toibot.js + toibot-bridge.js)
- Local Storage (chat history & session ID)
b. Server Layer (server.js)
- Express App serving static files & embed scripts
- API Endpoint (/api/chat)
- Flowise SDK integration & request validation
- Environment-driven configuration (FLOWISE_API_KEY, etc.)
c. External Service
- Flowise API (your self-hosted or cloud instance)

##### Relationships & Data Flows
1. User interacts with the chatbot UI in the browser.
2. Frontend sends HTTP POST /api/chat (and file uploads) to the Node server.
3. Server validates & sanitizes requests, then calls Flowise SDK → Flowise API.
4. Flowise streams responses back through the SDK.
5. Server streams data back to the browser in real time.
6. Browser renders the streamed messages, updates local storage, manages UI state (drag-drop, follow-ups).

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI code vs. server code vs. external API
- Proxy Pattern: server as intermediary to protect credentials
- Streaming / Event-driven: real-time message streaming
- Componentization: embeddable web component for easy integration

##### Technologies & Frameworks to Annotate
- Node.js + Express (server)
- flowise-sdk (server)
- HTML/CSS/Vanilla JS (frontend)
- Web Component API (embed/toibot.js)
- Local Storage (session & history)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        BrowserUI["Browser UI\n(index.html)"]:::frontend
        ChatbotLogic["chatbot.js"]:::frontend
        Styling1["styles.css"]:::frontend
        Styling2["custom.css"]:::frontend
        EmbeddableCore["toibot.js"]:::frontend
        BridgeScript["toibot-bridge.js"]:::frontend
        LocalStorage["Local Storage"]:::storage
    end

    %% Server Layer
    subgraph "Server Layer"
        StaticMiddleware["Express Static Middleware"]:::server
        APIProxy["/api/chat Proxy Logic"]:::server
        FlowiseSDK["Flowise SDK Module"]:::server
        EnvConfig["Env Config\n(.env.example)"]:::server
    end

    %% External Service
    FlowiseAPI["Flowise API"]:::external

    %% Project Files
    subgraph "Project Files"
        PackageJSON["package.json"]:::server
        PackageLock["package-lock.json"]:::server
        Readme["README.md"]:::server
    end

    %% Connections
    StaticMiddleware -->|"serves UI assets"| BrowserUI
    BrowserUI -->|"user interactions"| ChatbotLogic
    EmbeddableCore -.->|"loads widget"| BrowserUI
    BridgeScript -.->|"bridge events"| EmbeddableCore
    ChatbotLogic -->|"stores data"| LocalStorage
    ChatbotLogic -->|"POST /api/chat"| APIProxy
    APIProxy -->|"calls SDK"| FlowiseSDK
    FlowiseSDK -->|"HTTP stream"| FlowiseAPI
    FlowiseAPI -->|"stream response"| FlowiseSDK
    FlowiseSDK -->|"stream to client"| APIProxy
    APIProxy -->|"stream SSE"| ChatbotLogic
    EnvConfig --> APIProxy
    EnvConfig --> FlowiseSDK
    PackageJSON --> StaticMiddleware
    PackageLock --> StaticMiddleware
    Readme --> StaticMiddleware

    %% Click Events
    click BrowserUI "https://github.com/toi500/toibot/blob/main/public/index.html"
    click ChatbotLogic "https://github.com/toi500/toibot/blob/main/public/js/chatbot.js"
    click Styling1 "https://github.com/toi500/toibot/blob/main/public/css/styles.css"
    click Styling2 "https://github.com/toi500/toibot/blob/main/public/css/custom.css"
    click EmbeddableCore "https://github.com/toi500/toibot/blob/main/public/embed/toibot.js"
    click BridgeScript "https://github.com/toi500/toibot/blob/main/public/embed/toibot-bridge.js"
    click StaticMiddleware "https://github.com/toi500/toibot/blob/main/server.js"
    click APIProxy "https://github.com/toi500/toibot/blob/main/server.js"
    click EnvConfig "https://github.com/toi500/toibot/blob/main/.env.example"
    click PackageJSON "https://github.com/toi500/toibot/blob/main/package.json"
    click PackageLock "https://github.com/toi500/toibot/blob/main/package-lock.json"
    click Readme "https://github.com/toi500/toibot/blob/main/README.md"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#0288d1,color:#01579b
    classDef server fill:#e8f5e9,stroke:#388e3c,color:#1b5e20
    classDef external fill:#fff3e0,stroke:#f57c00,color:#e65100
    classDef storage fill:#f1f8e9,stroke:#827717,color:#33691e
```
