How toi500/toibot works
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)