Vezlo Assistant Chat

A complete chat widget solution with both a React component library and standalone admin application for AI-powered customer support.

What's Included

📦 NPM Package

• Reusable React Widget: Install via npm install @vezlo/assistant-chat
• TypeScript Support: Full type definitions included
• Customizable: Themes, colors, positioning, and behavior
• Real-time Streaming: Live AI responses with Server-Sent Events (SSE) streaming support
• Style Isolation: Shadow DOM support for conflict-free integration
• 📖 Complete Package Documentation

🖥️ Standalone Application

• Admin Dashboard: Configure widgets with live preview
• Playground: Test widgets in isolated environment
• Embed Code Generator: Get ready-to-use embed codes
• Docker Support: Easy deployment with Docker Compose
• Vercel Ready: One-click deployment to Vercel
• Shared Layout: MainLayout + Header provide a consistent, Vercel-style shell across every page
• Auth-Ready Context: AppProvider exposes user/workspace state, token helpers, and ProtectedRoute support for future login flows

Quick Start

For Developers (NPM Package)

npm install @vezlo/assistant-chat

import { Widget } from '@vezlo/assistant-chat';

function App() {
  const config = {
    uuid: 'your-widget-uuid',
    apiUrl: 'http://localhost:3000',
    apiKey: 'your-api-key',
    title: 'AI Assistant',
    themeColor: '#10b981',
    // ... other config
  };
  
  return <Widget config={config} />;
}

📖 Complete NPM Package Documentation

For Administrators (Standalone App)

This repository also contains a standalone admin application for configuring and managing widgets.

# Clone and run the standalone app
git clone https://github.com/vezlo/assistant-chat.git
cd assistant-chat
npm install
npm run dev

Features:

• Admin dashboard for widget configuration
• Live preview and playground
• Embed code generation
• Docker and Vercel deployment support
• Theme + widget matrices: see docs/THEME_WIDGET_CONFIG.md for every field, color mapping tips, and widget overrides

Prerequisites

• Assistant Server: Both components require a running Assistant Server
• Node.js 18+ and npm
• React 18+ (for package usage)
• Realtime Updates (Optional): For agent handoff + live message sync, provide Supabase Realtime credentials
  • VITE_SUPABASE_URL: Supabase project URL
  • VITE_SUPABASE_ANON_KEY: Supabase anon/public key
  • Without these, the widget works normally but won’t receive realtime updates

Features

Package Features

• ✅ React component library
• ✅ TypeScript support
• ✅ Tailwind CSS styling
• ✅ Real-time streaming (SSE-based backend streaming)
• ✅ Realtime updates (agent handoff, live message sync)
• ✅ Customizable themes
• ✅ Shadow DOM support
• ✅ API integration included

App Features

• ✅ Admin dashboard
• ✅ Live widget preview
• ✅ Playground testing
• ✅ Embed code generation
• ✅ Multiple widget management
• ✅ Human agent support (conversation management, agent handoff)
• ✅ Realtime updates (live message synchronization)
• ✅ Docker support
• ✅ Vercel deployment

Deployment Options

Package (NPM)

npm run build
npm pack  # Test locally
npm publish  # Publish to NPM

App (Vercel)

Deploy via Vercel Marketplace (Recommended)

The marketplace app deploys the frontend automatically, prompts you for the Assistant Server URL and optional API key, and ships both the chat UI and embeddable widget without any manual environment setup. After connecting your Vercel project you can immediately visit:

• Chat UI: https://your-project.vercel.app/

One-Click Deploy (GitHub Clone)

This clones the repo into your GitHub account, spins up a new Vercel project using the default main branch, and links the same Vezlo integration so the Assistant Chat deployment can gather its Assistant Server URL and API key during setup.

Manual Vercel CLI Deployment

# Install Vercel CLI
npm i -g vercel

# Deploy from local directory
vercel

# Set environment variables (required)
vercel env add VITE_ASSISTANT_SERVER_URL
vercel env add VITE_ASSISTANT_SERVER_API_KEY
# Optional: For realtime updates
vercel env add VITE_SUPABASE_URL
vercel env add VITE_SUPABASE_ANON_KEY

# Deploy to production
vercel --prod

App (Docker)

docker-compose up

Repository Structure

This repository contains both the NPM package and standalone application:

assistant-chat/
├── src/
│   ├── components/Widget.tsx    # Main widget component (used by both)
│   ├── api/                     # API services
│   ├── types/                   # TypeScript definitions
│   ├── utils/                   # Utility functions
│   ├── config/                  # Configuration
│   └── routes/                  # Standalone app pages
├── public/
│   └── widget.js               # Embed script
├── docs/                       # Documentation
├── README.md                   # This file (project overview)
├── PACKAGE_README.md           # NPM package documentation
└── package.json                # Package configuration

How It Works

• Same Widget Code: Both the NPM package and standalone app use the same Widget.tsx component
• Embed & Playground: WidgetPage.tsx powers the iframe, embed script, and playground preview using that same component
• NPM Package: Publishes the widget component as a reusable library
• Standalone App: Uses the widget component directly for admin interface and playground
• No Duplication: Single source of truth for the widget component

Layout & Auth Architecture

• AppProvider manages user, workspace, auth token, and exposes login/logout helpers plus ProtectedRoute for future API integration.
• Header & MainLayout deliver the new full-width, two-row dashboard shell (logo, workspace switcher, company badge, primary nav, profile dropdown).
• ConfigPage (dashboard) and every other route render inside MainLayout, so all future pages automatically inherit the header and spacing.
• LoginPage lives outside the layout and is already wired to AppProvider, making it ready for real authentication APIs.

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Codebase      │───▶│   src-to-kb     │───▶│ Knowledge Base  │
│   (Your Code)   │    │   (Analysis)    │    │   (Vector DB)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Chat Widget    │◄───│ Assistant Server│◀───│   AI Queries    │
│  (This Package) │    │   (Backend)     │    │   (RAG System)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Knowledge Base Integration

To enable AI-powered code analysis and intelligent responses, integrate with @vezlo/src-to-kb:

npm install -g @vezlo/src-to-kb
src-to-kb /path/to/your/codebase --output ./knowledge-base

The Assistant Server will automatically use this knowledge base to provide intelligent answers about your codebase.

API Integration

For detailed API integration documentation, see API Integration Guide.

Related Projects

• @vezlo/assistant-server - Backend API server
• @vezlo/src-to-kb - NPM package for code analysis
• @vezlo/ai-validator - AI validation tools

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/vezlo/assistant-chat.git
cd assistant-chat

# Install dependencies
npm install

# Start development server
npm run dev

# Build the package
npm run build

Issues & Support

• Package Issues: Assistant Chat Issues
• Server Issues: Assistant Server Issues
• General Questions: Assistant Server Discussions

📄 License

This project is dual-licensed:

• Non-Commercial Use: Free under AGPL-3.0 license
• Commercial Use: Requires a commercial license - contact us for details

---

Made with Love by Vezlo