AI Web Assistant

AI-powered chatbot that helps users interact with and navigate websites intelligently. The assistant can see web pages, understand their content, help fill forms, explain UI elements, and provide contextual support through natural conversation.

🎯 Features

• Smart Web Viewing: AI can see and analyze the current webpage
• Form Assistance: Help users fill forms with intelligent suggestions
• UI Explanation: Explain what different elements do
• Contextual Chat: Natural conversation about the webpage
• DOM Interaction: Click buttons, fill inputs, scroll pages
• Real-time Analysis: Instant feedback and suggestions
• Bubble Chat UI: Floating launcher with expandable chat panel
• Multiple Integration Options: Embed as script, web component, or iframe
• Dual Communication Modes: REST API (default) or WebSocket

🏗️ Architecture

ai-web-assistant/
├── frontend/                    # React client (NPM package)
│   ├── src/
│   │   ├── components/          # React components
│   │   ├── hooks/               # Custom hooks
│   │   ├── services/            # API clients
│   │   ├── store/               # State management
│   │   ├── types/               # TypeScript types
│   │   ├── config/              # Configuration
│   │   ├── index.ts             # Library export
│   │   ├── embed.ts             # Embed script
│   │   └── web-component.ts     # Web component
│   ├── package.json             # NPM package config
│   ├── tsconfig.json            # TypeScript config
│   └── README.md                # Frontend documentation
│
├── backend/                     # Node.js API (To be developed)
│   ├── src/
│   │   ├── routes/              # API routes
│   │   ├── controllers/         # Route handlers
│   │   ├── services/            # Business logic
│   │   ├── middleware/          # Express middleware
│   │   └── server.ts            # Server setup
│   ├── package.json
│   └── README.md
│
├── browser-extension/           # Chrome/Firefox extension
│   ├── manifest.json
│   ├── src/
│   ├── README.md
│   └── ...
│
├── docs/                        # Documentation
│   ├── ARCHITECTURE.md
│   ├── API.md
│   ├── SETUP.md
│   └── DEPLOYMENT.md
│
└── .github/workflows/           # CI/CD
    └── publish.yml              # Auto-publish to NPM

🛠️ Tech Stack

Frontend (Client)

• React - UI library
• TypeScript - Type safety
• Vite - Build tool
• Tailwind CSS - Styling
• Zustand - State management
• Axios - HTTP client
• Socket.io - WebSocket client

Backend (API Server)

• Node.js - Runtime
• Express - Web framework
• TypeScript - Type safety
• Puppeteer/Playwright - Browser automation
• OpenAI/Claude API - AI/LLM integration

Browser Extension

• Vanilla JS - Content script injection
• Chrome/Firefox APIs - DOM access

📦 NPM Package

Package Name: namnvb-ai-web-assistant-client

Installation

npm install namnvb-ai-web-assistant-client

Quick Start

Option 1: React Component

import { ChatBox, configureCommunication } from 'namnvb-ai-web-assistant-client';
import 'namnvb-ai-web-assistant-client/styles.css';

await configureCommunication({
  apiBaseUrl: 'https://api.yourdomain.com',
  webSocketUrl: 'https://api.yourdomain.com',
  mode: 'rest',
});

function App() {
  return (
    <ChatBox 
      pageContext={{
        url: window.location.href,
        title: document.title
      }}
    />
  );
}

Option 2: Embed Script

<script 
  src="https://unpkg.com/namnvb-ai-web-assistant-client/dist/embed.js"
  data-api-base="https://api.yourdomain.com"
  data-websocket-url="https://api.yourdomain.com"
  data-mode="rest"
></script>

Option 3: Web Component

<script src="https://unpkg.com/namnvb-ai-web-assistant-client/dist/web-component.js"></script>
<ai-web-assistant 
  api-base="https://api.yourdomain.com"
  websocket-url="https://api.yourdomain.com"
  communication-mode="rest"
></ai-web-assistant>

Override Backend Domain

You can override the backend domain from the host app instead of relying only on .env.

React / npm import

import { configureCommunication } from 'namnvb-ai-web-assistant-client';

await configureCommunication({
  apiBaseUrl: 'https://api.yourdomain.com',
  webSocketUrl: 'https://api.yourdomain.com',
});

Embed script attributes

• data-api-base sets the REST API base URL
• data-websocket-url sets the WebSocket URL
• data-mode sets the communication mode

Web component attributes

• api-base sets the REST API base URL
• websocket-url sets the WebSocket URL
• communication-mode sets the communication mode

Links

• 📦 NPM Registry: namnvb-ai-web-assistant-client
• 📖 Frontend README: frontend/README.md
• 📚 NPM Publishing Guide: frontend/NPM-PUBLISHING-GUIDE.md
• 🔧 Development Guide: frontend/DEVELOPMENT.md

🚀 Getting Started

1. Install Dependencies

# Frontend
cd frontend
npm install

# Backend (when ready)
cd ../backend
npm install

2. Configure Environment

# Frontend
cd frontend
cp .env.example .env

.env settings:

VITE_COMMUNICATION_MODE=rest
VITE_API_BASE_URL=http://localhost:5000
VITE_WEBSOCKET_URL=http://localhost:5000
VITE_ENABLE_DEBUG=true

3. Start Development

# Frontend dev server
cd frontend
npm run dev
# Runs on http://localhost:3000

# Backend dev server (when ready)
cd backend
npm run dev
# Runs on http://localhost:5000

🔌 3 Ways to Embed Client

The client can be embedded in any website in 3 ways:

| Method | Best For | DOM Access | |--------|----------|-----------| | Embed Script | Production websites | ✅ Full access | | Web Component | Modern apps | ✅ Full access | | Iframe | Isolated environments | ⚠️ postMessage |

See detailed guide: frontend/README.md#-3-ways-to-embed-client--read-dom

🔄 Communication Modes

REST API (Default)

• HTTP-based request/response
• Simpler setup
• Good for standard chat flows
• Uses VITE_API_BASE_URL by default

WebSocket

• Real-time bidirectional
• Better for streaming
• Auto-reconnect support
• Uses VITE_WEBSOCKET_URL by default

Configure in .env:

VITE_COMMUNICATION_MODE=rest        # or 'websocket'

📋 API Endpoints (Backend - To be implemented)

REST API

• POST /api/chat - Send chat message
• POST /api/analyze - Analyze webpage
• GET /api/chat/history/:conversationId - Get history
• POST /api/dom/interact - Execute DOM action
• GET /api/health - Health check

WebSocket Events

Client → Server:

• chat:message - Send message
• chat:action - Execute action

Server → Client:

• chat:response - AI response
• chat:action - Request action
• chat:status - Status update
• chat:error - Error message
• connection:ready - Connection ready

📚 Documentation

• 📖 Frontend README - Client setup & usage
• 📦 NPM Publishing Guide - How to publish
• 🔧 Development Guide - Contributing
• 📝 Changelog - Version history

🔐 Environment Variables

Frontend

# Communication
VITE_COMMUNICATION_MODE=rest              # 'rest' or 'websocket'
VITE_API_BASE_URL=http://localhost:5000  # Backend URL
VITE_API_TIMEOUT=30000                    # Request timeout (ms)

# WebSocket
VITE_WEBSOCKET_URL=http://localhost:5000
VITE_WEBSOCKET_RECONNECT_DELAY=1000
VITE_WEBSOCKET_RECONNECT_ATTEMPTS=5

# Features
VITE_ENABLE_DEBUG=true                    # Debug logging
VITE_ENABLE_STREAMING=true                # AI streaming

🏗️ Development Status

✅ Completed

• Frontend client setup
• React components
• REST API client
• WebSocket client
• State management
• TypeScript support
• 3 embedding options
• NPM package configuration
• Full documentation
• GitHub Actions setup

🚧 In Progress

• Backend API development
• AI/LLM integration
• Browser extension

📋 Planned

• Vue.js component
• Angular component
• React Native support
• Advanced streaming
• Plugin system
• Analytics

🚀 Publishing to NPM

One-time Setup

# Login to NPM
npm login

# Create NPM_TOKEN secret in GitHub
# Settings → Secrets → New repository secret
# Name: NPM_TOKEN
# Value: Your NPM auth token

Publish Process

cd frontend

# Update version
npm version patch  # 0.1.0 → 0.1.1

# Tag will be created automatically
# Push tag to trigger GitHub Actions
git push origin v0.1.1

# GitHub Actions will auto-publish to NPM

See detailed guide: frontend/NPM-PUBLISHING-GUIDE.md

🤝 Contributing

1. Fork repository
2. Create feature branch: git checkout -b feature/your-feature
3. Make changes
4. Run type check: npm run type-check
5. Build: npm run build
6. Commit: git commit -m "feat: your feature"
7. Push: git push origin feature/your-feature
8. Create Pull Request

See: frontend/DEVELOPMENT.md

📞 Support

• 📖 Check Documentation
• 🐛 Report Issues
• 💬 Start Discussion

📝 License

MIT - See LICENSE file

🎯 Roadmap

• 🌍 Multi-language support
• 🚀 Advanced form auto-fill
• 📊 Performance metrics
• 📱 Mobile app version
• 🔗 Website integrations
• 🧠 Custom AI training
• 💼 Enterprise features
• ⚙️ API rate limiting

Made with ❤️ by the AI Web Assistant Team

Current Status: 🟢 Active Development - Frontend Complete, Backend In Progress