Automate customer conversations across Facebook Messenger, Instagram DM, and WhatsApp with intelligent, context-aware AI chatbots
Assist+ is a modern, open-source SaaS platform that enables businesses to deploy intelligent AI chatbots across multiple messaging platforms. Built with performance and scalability in mind, it leverages cutting-edge technologies to deliver cost-effective, enterprise-grade customer service automation.
- 🚀 Production-Ready - Multi-tenant architecture with comprehensive authentication and authorization
- 💰 Cost-Effective - Semantic caching reduces LLM API costs by 40-80% using pgvector embeddings
- 🧠 Intelligent - RAG-powered responses with knowledge base integration and conversation context
- ⚡ High Performance - Built on Bun runtime (4x faster than Node.js) with optimized database queries
- 🌍 Multilingual - Native support for English and Arabic with full RTL (Right-to-Left) layout
- 🔧 Developer-Friendly - Type-safe codebase, comprehensive API, and extensive documentation
- Facebook Messenger - Complete OAuth 2.0 flow with automatic token refresh and page management
- Instagram Direct Messages - Full integration with automatic account discovery and unified inbox
- WhatsApp Business (Coming Soon) - Enterprise messaging via Meta's Business API
- Smart Response Engine - Powered by OpenRouter with support for multiple LLM providers
- Knowledge Base - Upload and manage articles with automatic semantic embedding generation
- Semantic Caching - PostgreSQL pgvector-based caching for intelligent response reuse
- Context Awareness - Maintains conversation history and business context across interactions
- RAG (Retrieval Augmented Generation) - Retrieves relevant knowledge to enhance responses
- Multi-Tenant Architecture - Secure isolation with tenant-level data segregation
- Business Context Provider - Smart business selection with URL-based routing
- Conversation Management - 7-day conversation history with full message tracking
- Lead Detection (In Development) - Automatically identify and capture sales opportunities
- Order Tracking (In Development) - Extract order details and customer addresses from conversations
- Modern Dashboard - Beautiful UI built with Next.js 14, Tailwind CSS, and shadcn/ui
- Type-Safe API - Full TypeScript coverage with Zod validation
- Background Jobs - Robust message queue powered by BullMQ and Redis
- Database Migrations - Version-controlled schema changes with Drizzle ORM
- Comprehensive Testing - Unit and integration tests for API and frontend
Phase 1: MVP Foundation (60% Complete)
- Core platform architecture and multi-tenant infrastructure
- Facebook Messenger and Instagram DM integrations
- AI response engine with OpenRouter integration
- Knowledge base with semantic embeddings
- Semantic caching with pgvector
- Message queue and background job processing
- Modern dashboard with business management
- Fixed flow builder for common queries
- Lead and order detection capabilities
Phase 2: Growth & Scale
- Self-service tenant registration and onboarding
- Subscription billing integration (Stripe)
- Advanced analytics and insights dashboard
- Human agent handoff workflow
- Real-time notifications and alerts
- Mobile-responsive optimization
Phase 3: Enterprise Features
- WhatsApp Business API integration
- Multi-business support per tenant
- Advanced workflow builder with branching logic
- Native mobile applications (iOS/Android)
- Public API for third-party integrations
- White-label capabilities
- Bun - Next-generation JavaScript runtime (4x faster than Node.js)
- TypeScript - Type-safe development with strict mode enabled
- Turborepo - High-performance monorepo build system
- Hono - Ultra-fast web framework with Express-like API
- Drizzle ORM - Type-safe SQL ORM with excellent TypeScript support
- PostgreSQL 16 - Advanced relational database
- pgvector - Vector similarity search for embeddings
- Redis - In-memory data store for caching and queues
- BullMQ - Robust job queue for background processing
- Next.js 14 - React framework with App Router and Server Components
- Tailwind CSS - Utility-first CSS framework
- shadcn/ui - High-quality, accessible React components
- Vercel AI SDK - Streaming LLM responses and AI integration
- OpenRouter - Unified LLM API with free tier models
- Meta Graph API - Facebook and Instagram messaging
- OpenAI (Optional) - Alternative embedding provider
Ensure you have the following installed:
You'll also need:
- Meta Developer account with app credentials
- OpenRouter API key (free tier available)
# Clone the repository
git clone https://github.com/mu7ammad-3li/assist-plus.git
cd assist-plus
# Install dependencies
bun install
# Configure environment variables
cp .env.example .env
# Edit .env with your credentials (see Configuration section below)
# Start infrastructure services
docker compose up -d db redis
# Run database migrations
bun run db:migrate
# (Optional) Seed with sample data
bun run db:seed
# Start development servers
bun run devThe application will be available at:
- Frontend Dashboard: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
Create a .env file in the project root with the following required variables:
# Database
DATABASE_URL=postgresql://assistplus:password@localhost:5432/assistplus
# Redis
REDIS_URL=redis://localhost:6379
# Authentication
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
# Meta Platform
META_APP_ID=your-meta-app-id
META_APP_SECRET=your-meta-app-secret
META_VERIFY_TOKEN=your-webhook-verification-token
# AI Provider
OPENROUTER_API_KEY=sk-or-v1-your-api-keySee .env.example for all available configuration options.
assist-plus/
├── apps/
│ ├── api/ # Backend API (Bun + Hono)
│ │ ├── src/
│ │ │ ├── routes/ # API endpoints
│ │ │ ├── services/ # Business logic
│ │ │ ├── db/ # Database schema and migrations
│ │ │ └── lib/ # Utilities and helpers
│ │ └── tests/ # API tests
│ ├── web/ # Frontend Dashboard (Next.js)
│ │ ├── app/ # App Router pages
│ │ ├── components/ # React components
│ │ └── lib/ # Client utilities
│ └── admin/ # Admin Panel (Coming Soon)
├── packages/
│ ├── shared/ # Shared types, validators, utilities
│ └── ui/ # Shared UI components
├── docs/ # Documentation
├── docker/ # Docker configurations
└── .claude/ # Claude Code AI configuration
For detailed architecture information, see STRUCTURE.md.
# Development
bun run dev # Start all apps in development mode
bun run dev:api # Start backend only
bun run dev:web # Start frontend only
# Database Operations
bun run db:generate # Generate migration from schema changes
bun run db:migrate # Apply pending migrations
bun run db:seed # Populate database with test data
bun run db:studio # Open Drizzle Studio (visual database editor)
# Testing
bun test # Run all tests
bun test:api # Run backend tests
bun test:web # Run frontend tests
bun test:coverage # Generate coverage report
# Code Quality
bun run lint # Lint all packages
bun run format # Format code with Prettier
bun run typecheck # TypeScript type checking
# Production
bun run build # Build all apps for production
bun run start # Start production servers-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes
- Backend code:
apps/api/src/ - Frontend code:
apps/web/ - Shared code:
packages/shared/
- Backend code:
-
Test thoroughly
bun test bun run lint bun run typecheck -
Commit with conventional commits
git commit -m "feat(api): add lead detection endpoint" -
Push and create a pull request
git push origin feature/your-feature-name
This project includes custom Claude Code configurations for AI-assisted development:
# Scaffold new API route
/scaffold-route feature-name
# Scaffold new Next.js page
/scaffold-page feature/new-page
# Generate tests
/add-test feature-name
# Create database migration
/create-migrationSee .claude/README.md for complete documentation.
# Build production images
docker compose -f docker/docker-compose.prod.yml build
# Start all services
docker compose -f docker/docker-compose.prod.yml up -d
# Run database migrations
docker compose exec api bun run db:migrate- Backend (API): Deploy to Fly.io, Railway, or any VPS
- Frontend (Web): Deploy to Vercel (recommended) or Netlify
- Database: Use managed PostgreSQL from Supabase, Neon, or AWS RDS
For comprehensive deployment instructions, see docs/DEPLOYMENT.md.
- STRUCTURE.md - Project architecture and code organization
- PROGRESS.md - Development roadmap and task tracking
- CONTRIBUTING.md - Contribution guidelines
- SECURITY.md - Security policies and vulnerability reporting
- docs/API.md - REST API documentation
- docs/DEPLOYMENT.md - Production deployment guide
- docs/META_SETUP.md - Meta platform integration setup
We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or feedback, your help is appreciated.
- Fork the repository
- Read CONTRIBUTING.md for guidelines
- Check PROGRESS.md for open tasks
- Create a feature branch
- Submit a pull request
- Write clean, maintainable TypeScript code
- Follow existing code patterns and conventions
- Add tests for new features
- Update documentation as needed
- Use Conventional Commits for commit messages
See CONTRIBUTING.md for detailed information.
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright © 2026 Muhammad Ali
Built with excellent open-source tools:
- Bun - For exceptional JavaScript runtime performance
- Vercel - For the powerful AI SDK
- OpenRouter - For accessible LLM API access
- Meta - For comprehensive messaging APIs
- All the amazing open-source projects that make this possible
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 🔒 Security: See SECURITY.md for vulnerability reporting
- 📧 Contact: mu7ammad.3lii2@gmail.com
If you find this project useful, please consider giving it a star! It helps others discover the project and motivates continued development.
Documentation • Contributing • License • Changelog
Built with ❤️ using Bun, TypeScript, and AI