Bolnee-Chat: Self-Hosted RAG Chatbot for Business Websites

Bolnee-Chat is a self-hosted Retrieval-Augmented Generation (RAG) chatbot platform designed for business website integration. It enables users to create AI bots grounded in specific website content and uploaded documents, deployable via a simple two-line JavaScript snippet, and hosted entirely on the user's own infrastructure to avoid vendor lock-in and per-message billing.

Core Functionality and RAG Implementation

Bolnee-Chat uses a RAG pipeline to ensure chatbot responses are grounded in provided source material rather than relying solely on the LLM's internal knowledge.

Knowledge Ingestion

The platform supports two primary methods for adding knowledge:

  • Website Crawling: A Python-based crawler (crawler/crawler.py) extracts content from h1, h2, p, and li tags. The crawler respects robots.txt and handles sitemaps and homepages to deduplicate and save content into JSON files.
  • File Uploads: The system ingests PDFs, TXT, MD, and DOCX files.

Indexing and Retrieval

Ingested data is chunked and stored in a SQLite database using Full-Text Search (FTS). When a user queries the bot, the system builds grounded prompts based on these chunks, providing citations for the sources used in the response. A configurable fallback message is triggered if no matching sources are found in the database.

Technical Architecture and Stack

Bolnee-Chat is built with a modern TypeScript and Python stack, utilizing a lightweight database for easy deployment.

Tech Stack

  • Frontend: React 19, Vite, TypeScript, and Tailwind CSS.
  • Backend: Express (Node.js 18+) and Python 3.10+ (for the crawler).
  • Database: SQLite (via better-sqlite3) for storing chatbots, sources, chunks, and messages.
  • LLM Integration: Supports any OpenAI-compatible provider, including OpenRouter, OpenAI, Groq, Ollama, and vLLM.

Security and Storage

  • API Key Encryption: Provider API keys and base URLs are encrypted using AES-256-GCM and are never exposed in the client-side embed snippet.
  • Avatar Management: User-uploaded avatars (PNG, JPG, WEBP up to 2MB) are converted from data URLs to stored files accessible via /api/public/avatar/:id.

Deployment and Integration

The platform is designed for rapid deployment across various hosting environments, including Vercel and Cloudflare Pages.

Integration Process

Integration is achieved by adding a configuration object and a script tag before the closing </body> tag of a website:

<script>
  window.BotConfig = {
    botName: "Customer Bot",
    avatar: "https://your-domain/api/public/avatar/BOT_ID",
    chatUrl: "https://your-domain/api/public/chat/BOT_ID",
    accentColor: "#111111",
    greeting: "Hi! How can I help?",
    theme: "dark"
  };
</script>
<script src="https://your-domain/chatbot-widget.js" async></script>

Widget Features

  • Persistence: Uses localStorage to store VISITOR_ID and chat history, ensuring that greetings only appear once and conversations persist across sessions.
  • Streaming: Implements Server-Sent Events (SSE) for real-time response streaming.
  • UI/UX: Features a floating bubble in the bottom-right, a sliding window (360x520), and theme-aware styling (light, dark, or auto).

Administrative Management

Bolnee-Chat includes a comprehensive dashboard for managing multiple bots and monitoring interactions.

Bot Management

Administrators can customize the bot's appearance (name, avatar, accent color, and theme) and configure the LLM provider by fetching available models directly from the API.

Analytics and Export

Visitor chats are grouped by visitorId and IP address. The dashboard provides statistics on total messages and active sessions (defined as distinct visitors in the last 5 minutes). Chat logs can be exported in CSV (Excel), JSON, or PDF formats.

Sources