- Overview
- Key Features
- Why PrivexBot?
- Architecture
- Quick Start
- Documentation
- Technology Stack
- Project Structure
- Development
- Deployment
- Contributing
- License
- Support
PrivexBot is a privacy-focused, multi-tenant SaaS platform that empowers organizations to build, train, and deploy AI-powered chatbots using their own data. Unlike traditional platforms, all AI workloads—including data ingestion, training, and inference—are executed within Secret VM environments (Trusted Execution Environments/TEEs) to ensure:
- 🔒 Confidential Computation - Data encrypted in memory during processing
- 🛡️ Remote Attestation - Cryptographically verify code integrity
- 🔐 Zero Data Leakage - Even platform administrators cannot access plaintext data
- ✅ Regulatory Compliance - Built for HIPAA, GDPR, and enterprise security requirements
PrivexBot provides two powerful creation modes:
- Simple Chatbots - Form-based interface for quick FAQ bots and simple Q&A assistants
- Advanced Chatflows - Visual drag-and-drop workflow builder (like n8n/Dify) for complex, multi-step conversational AI
Both modes support:
- 📚 RAG-powered Knowledge Bases - Import from files, websites, Notion, Google Docs
- 🌍 Multi-Channel Deployment - Website widget, Discord, Telegram, WhatsApp, API
- 📊 Lead Capture - Built-in lead generation and analytics
- 🎨 Full Customization - Branding, colors, behavior, and deployment options
- Secret VM Execution - All AI inference runs in Trusted Execution Environments
- End-to-End Encryption - Data encrypted at rest and in memory
- Multi-Provider Authentication - Email, MetaMask, Phantom, Keplr wallet support
- RBAC Permissions - Granular role-based access control
- Zero-Trust Architecture - No plaintext data exposure to platform
- Dual Creation Modes:
- Form-Based - Quick chatbot creation with guided forms
- Visual Workflow - Drag-and-drop node editor for complex logic
- Draft-First Architecture - Preview and test before deployment
- Live Testing - Test with real AI responses during creation
- Version Control - Track and rollback changes
- Multi-Source Import:
- 📄 File Upload (PDF, Word, Text, CSV, JSON)
- 🌐 Website Scraping (multi-page crawl with Crawl4AI)
- 📝 Google Docs & Sheets
- 📋 Notion pages and databases
- ✍️ Direct text paste
- Smart Chunking - 4 strategies (size-based, heading-based, page-based, semantic)
- Document Annotations - Add context, importance, usage instructions
- Background Processing - Async document indexing with Celery
- Vector Search - FAISS, Qdrant, Weaviate, Milvus, Pinecone support
- Website Embed - JavaScript widget (~50KB) for any website
- Discord Bot - Native Discord integration with webhooks
- Telegram Bot - Full Telegram Bot API support
- WhatsApp Business - WhatsApp Business API integration
- Zapier Webhook - Connect to 5000+ apps via Zapier
- Direct API - RESTful API for custom integrations
- Optional Lead Capture - Collect email, name, phone, custom fields
- Smart Timing - Before chat, during chat, or after N messages
- Geolocation - Automatic IP-based location detection
- Analytics Dashboard - Geographic distribution, conversion tracking
- Privacy Controls - GDPR-compliant with consent management
- Widget Customization - Position, colors, greeting, branding
- Brand Control - White-label options, custom domains
- Behavior Configuration - System prompts, personality, tone
- Channel-Specific Settings - Different configs per deployment channel
- ✅ Data Privacy Guaranteed - Secret VM ensures data never leaves TEE
- ✅ Regulatory Compliance - Meet HIPAA, GDPR, SOC 2 requirements
- ✅ On-Premise Deployment - Deploy to your own infrastructure
- ✅ Audit Trails - Complete logging and attestation records
- ✅ Multi-Tenant - Manage multiple clients/organizations
- ✅ White-Label - Rebrand as your own service
- ✅ Team Collaboration - Workspaces for different departments
- ✅ API Access - Programmatic bot management
- ✅ Open Source - Full codebase transparency
- ✅ Modern Stack - FastAPI, React 19, TypeScript
- ✅ Docker Ready - One-command deployment
- ✅ Extensible - Plugin architecture for custom nodes
- ✅ Production Ready - Battle-tested architecture
- ✅ Scalable - Handles millions of messages
- ✅ Monetization - Built-in subscription and billing hooks
- ✅ Analytics - Usage tracking and insights
PrivexBot is built as a monorepo with three main packages:
┌─────────────────────────────────────────────────────────────┐
│ PrivexBot Platform │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Frontend (React + TypeScript) │ │
│ │ - Admin dashboard for bot creation │ │
│ │ - Visual workflow builder (ReactFlow) │ │
│ │ - Analytics and lead management │ │
│ │ 📍 Port 3000 (Dev) / 443 (Prod) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↕ REST API │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Backend (FastAPI + Python) │ │
│ │ - Multi-tenant API │ │
│ │ - RAG knowledge base processing │ │
│ │ - Secret AI inference (TEE) │ │
│ │ - Multi-channel integrations │ │
│ │ 📍 Port 8000 │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↕ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Infrastructure │ │
│ │ - PostgreSQL (Multi-tenant data) │ │
│ │ - Redis (Draft storage, sessions, cache) │ │
│ │ - Celery (Background tasks) │ │
│ │ - Vector DB (FAISS/Qdrant/Pinecone) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Widget (Vanilla JavaScript) │
│ - Embeddable chat widget (~50KB) │
│ - Framework-agnostic │
│ - Works on any website │
│ 📍 Served via CDN or backend │
└─────────────────────────────────────────────────────────────┘
- Multi-Tenancy - Organization → Workspace → Resources hierarchy
- Draft-First - All creation happens in Redis before database commit
- Background Processing - Never block API requests (Celery tasks)
- Backend-Only AI - Secret AI never exposed to frontend
- Unified API - Same endpoints work for chatbots and chatflows
- Plugin Architecture - Extensible with custom nodes and integrations
📖 For detailed architecture, see ARCHITECTURE.md
- Docker (20.10+) and Docker Compose (2.0+)
- Node.js (20+) - For local frontend development
- Python (3.11+) - For local backend development
- Git - For cloning the repository
git clone https://github.com/privexbot/privexbot.git
cd privexbot# Copy environment files
cp .env.example .env
cp .env.prod.example .env.prod
# Edit .env with your settings
nano .env# Start all services (frontend + backend + database + redis)
docker compose up -d
# View logs
docker compose logs -f
# Stop services
docker compose downServices will be available at:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
# Build production images
./scripts/build-prod.sh
# Test locally
./scripts/test-prod.sh
# Deploy to Docker Hub
./scripts/deploy-prod.sh📖 For detailed setup, see GETTING_STARTED.md
- Architecture Summary - Complete technical overview
- Database Models - Database models and components
- Multi-Tenancy Details - Tenant isolation implementation
- Draft Mode Architecture - Redis-based draft system
- Knowledge Base Flow - RAG implementation
- Deployment Architecture - Multi-channel deployment
- API Reference - REST API endpoints and schemas
- Backend Guide - Python backend architecture
- Frontend Guide - React frontend architecture
- Widget Guide - Embeddable widget development
- Docker Setup for dev - Local development environment
- Local Deployment Guide - Deploy to localhost
- Docker Setup for SecretVM deployment - Production environment
- Production Deployment Guide - Deploy to production
- Complete Architecture - Deep dive with diagrams
- Framework: FastAPI (Python 3.11+)
- ORM: SQLAlchemy 2.0+
- Database: PostgreSQL 15+ (with pgvector extension)
- Cache/Session: Redis 7+
- Task Queue: Celery with Redis broker
- Migrations: Alembic
- Validation: Pydantic V2
- Package Manager: uv
- Testing: pytest, pytest-asyncio
- Framework: React 19
- Language: TypeScript 5+
- Build Tool: Vite 5+
- Styling: Tailwind CSS + shadcn/ui
- State Management: React Context + Zustand
- Forms: React Hook Form + Zod validation
- Workflow Builder: ReactFlow
- HTTP Client: Axios
- Testing: Vitest, React Testing Library
- Language: Vanilla JavaScript (ES6+)
- Build: Webpack 5
- Size: ~50KB minified + gzipped
- Compatibility: All modern browsers (Chrome, Firefox, Safari, Edge)
- Containerization: Docker + Docker Compose
- Reverse Proxy: Nginx
- Vector Stores: FAISS, Qdrant, Weaviate, Milvus, Pinecone
- Embeddings: OpenAI, Hugging Face, Cohere (selfhosted)
- AI Inference: Secret AI (Trusted Execution Environment)
- Website Scraping: Crawl4AI, Firecrawl, Jina Reader
- Document Parsing: Unstructured.io, PyMuPDF, python-docx
- Cloud Sources: Google Docs API, Notion API, Google Sheets API
- Messaging: Discord.py, python-telegram-bot, Twilio (WhatsApp)
- Geolocation: MaxMind GeoIP2, IP2Location
- Authentication: MetaMask, Phantom, Keplr wallet support
privexbot/
├── backend/ # Python FastAPI backend
│ ├── src/app/
│ │ ├── main.py # FastAPI entry point
│ │ ├── api/v1/routes/ # API endpoints
│ │ │ ├── auth.py # Authentication
│ │ │ ├── chatbot.py # Chatbot CRUD
│ │ │ ├── chatflows.py # Chatflow CRUD
│ │ │ ├── knowledge_bases.py # KB management
│ │ │ ├── kb_draft.py # Draft mode endpoints
│ │ │ ├── documents.py # Document processing
│ │ │ ├── leads.py # Lead management
│ │ │ ├── public.py # Public API
│ │ │ └── webhooks/ # Platform webhooks
│ │ ├── models/ # SQLAlchemy models
│ │ │ ├── user.py
│ │ │ ├── organization.py
│ │ │ ├── workspace.py
│ │ │ ├── chatbot.py
│ │ │ ├── chatflow.py
│ │ │ ├── knowledge_base.py
│ │ │ └── ...
│ │ ├── schemas/ # Pydantic schemas
│ │ ├── services/ # Business logic
│ │ │ ├── auth_service.py
│ │ │ ├── chatbot_service.py
│ │ │ ├── chatflow_service.py
│ │ │ ├── chatflow_executor.py
│ │ │ ├── kb_draft_service.py
│ │ │ ├── inference_service.py # Secret AI
│ │ │ ├── retrieval_service.py # RAG
│ │ │ └── ...
│ │ ├── auth/strategies/ # Auth providers
│ │ ├── integrations/ # External integrations
│ │ ├── chatflow/nodes/ # Chatflow node types
│ │ ├── tasks/ # Celery tasks
│ │ └── alembic/ # Database migrations
│
├── frontend/ # React TypeScript frontend
│ ├── src/
│ │ ├── pages/
│ │ │ ├── Dashboard.tsx
│ │ │ ├── ChatbotBuilder.tsx # Form-based builder
│ │ │ ├── ChatflowBuilder.tsx # Visual builder
│ │ │ ├── KBCreationWizard.tsx # Draft KB creation
│ │ │ ├── KnowledgeBase.tsx
│ │ │ ├── LeadsDashboard.tsx
│ │ │ └── Deployments.tsx
│ │ ├── components/
│ │ │ ├── chatbot/ # Chatbot components
│ │ │ ├── chatflow/ # ReactFlow components
│ │ │ ├── kb/ # KB creation (draft)
│ │ │ └── shared/ # Shared components
│ │ ├── api/ # API clients
│ │ ├── contexts/ # React contexts
│ │ ├── hooks/ # Custom hooks
│ │ └── lib/ # Utilities
│
├── widget/ # Embeddable chat widget
│ ├── src/
│ │ ├── index.js # Entry point
│ │ ├── ui/
│ │ │ ├── ChatBubble.js
│ │ │ ├── ChatWindow.js
│ │ │ ├── MessageList.js
│ │ │ ├── InputBox.js
│ │ │ └── LeadForm.js
│ │ ├── api/client.js # Backend API
│ │ └── styles/widget.css
│ ├── build/widget.js # Compiled output
│ └── webpack.config.js
│
├── docs/ # Documentation
│ ├
│
│
├── scripts/ # Utility scripts
│ ├──
│
├── docker-compose.dev.yml # Development compose
├── docker-compose.yml # Production compose
├── .env.example # Development env template
├── .env # Production env template
├── README.md # This file
📖 For detailed structure explanation, see ARCHITECTURE.md
Frontend:
cd frontend
# Install dependencies
npm install
# Start dev server
npm run devWidget:
cd widget
# Install dependencies
npm install
# Build for development
npm run dev
# Build for production
npm run build# Backend tests
cd backend
pytest
# Frontend tests
cd frontend
npm run test
# E2E tests
npm run test:e2e# Backend linting
cd backend
ruff check .
mypy app/
# Frontend linting
cd frontend
npm run lint
# Format code
npm run format📖 For detailed development workflow, see CONTRIBUTING.md
Best for: MVPs, small teams, 1-100 customers
For serving the widget globally:
# Using Cloudflare (FREE)
1. Sign up at cloudflare.com
2. Add your domain
3. Create cdn.yourdomain.com subdomain
4. Upload widget.js to Cloudflare Workers
5. Update WIDGET_CDN_URL in .env.prod├── backend
│ ├── __init__.py
│ ├── pyproject.toml
│ ├── src
│ │ ├── Dockerfile
│ │ ├── __init__.py
│ │ ├── alembic.ini
│ │ └── app
│ │ ├── __init__.py
│ │ ├── alembic
│ │ │ ├── __init__.py
│ │ │ ├── env.py
│ │ │ ├── script.py.mako
│ │ │ └── versions
│ │ ├── api
│ │ │ ├── __init__.py
│ │ │ └── v1
│ │ │ ├── __init__.py
│ │ │ ├── dependencies.py
│ │ │ └── routes
│ │ │ ├── __init__.py
│ │ │ ├── auth.py
│ │ │ ├── chatbot.py
│ │ │ ├── org.py
│ │ │ └── workspace.py
│ │ ├── auth
│ │ │ ├── __init__.py
│ │ │ └── strategies
│ │ │ ├── __init__.py
│ │ │ ├── cosmos.py
│ │ │ ├── email.py
│ │ │ ├── evm.py
│ │ │ └── solana.py
│ │ ├── core
│ │ │ ├── __init__.py
│ │ │ ├── config.py
│ │ │ └── security.py
│ │ ├── db
│ │ │ ├── __init__.py
│ │ │ ├── base.py
│ │ │ ├── base_class.py
│ │ │ └── session.py
│ │ ├── main.py
│ │ ├── models
│ │ │ ├── __init__.py
│ │ │ ├── auth_identity.py
│ │ │ ├── chatbot.py
│ │ │ ├── organization.py
│ │ │ ├── organization_member.py
│ │ │ ├── user.py
│ │ │ ├── workspace.py
│ │ │ └── workspace_member.py
│ │ ├── schemas
│ │ │ ├── __init__.py
│ │ │ ├── chatbot.py
│ │ │ ├── organization.py
│ │ │ ├── token.py
│ │ │ ├── user.py
│ │ │ └── workspace.py
│ │ ├── services
│ │ │ ├── __init__.py
│ │ │ ├── auth_service.py
│ │ │ ├── permission_service.py
│ │ │ └── tenant_service.py
│ │ ├── tasks
│ │ │ ├── __init__.py
│ │ │ └── celery_worker.py
│ │ ├── tests
│ │ │ ├── __init__.py
│ │ │ ├── conftest.py
│ │ │ ├── test_auth.py
│ │ │ └── test_tenancy.py
│ │ └── utils
│ │ ├── __init__.py
│ │ └── redis.py
│ └── uv.lock
What: Entry point of the FastAPI application.
Responsibilities:
- Instantiate FastAPI app
- Include API routers
- Mount middleware, CORS, error handlers
Integration:
- Imports routes from
api/v1/routes/ - Uses config from
core/config.py
What: HTTP API layer, versioned (v1, v2, ...).
Responsibilities:
- Defines route handlers (auth.py, chatbot.py, etc.)
- Contains dependency injections (auth guards, permissions)
Integration:
- Uses Pydantic schemas for validation
- Calls services for business logic
- Uses auth for authentication/authorization
What: Authentication strategies (email, blockchain wallets, etc.)
Responsibilities:
- Email login/signup
- Ethereum, Solana, Cosmos wallet auth
- Nonce creation, signature verification
Integration:
- Called by API auth routes
- Uses Redis (via utils/redis.py) for nonce caching
What: App-wide settings and security utilities.
Responsibilities:
- Config loader (
config.py) - JWT, password hashing (
security.py) - Constants and shared utilities
Integration:
- Used throughout app startup, services, and routes
What: Database connection and session management.
Responsibilities:
- SQLAlchemy session and base models
- Initializes ORM base classes and mixins
Integration:
- Used by models, services, and API layers
What: ORM models representing database tables.
Responsibilities:
- User, Organization, Workspace models
- Relationships and tenancy via foreign keys
Integration:
- Used by services, Alembic for migrations
What: Pydantic schemas for request validation and response serialization.
Responsibilities:
- Validate API inputs
- Control API outputs
Integration:
- Used in API routes and sometimes in services
What: Business logic layer.
Responsibilities:
- Authentication service (login/signup/JWT)
- Tenant resolution (org/workspace)
- Permission mapping (roles → permissions)
Integration:
- Called by API route handlers
What: Helper functions and utilities.
Responsibilities:
- Redis client
- Common helpers used across modules
Integration:
- Used by auth, services, tasks
What: Background task runners (e.g., Celery workers).
Responsibilities:
- Runs asynchronous jobs (e.g., email sending)
Integration:
- Linked via async workflows, message brokers
What: Backend unit and integration tests.
Responsibilities:
- Pytest tests
- Test fixtures and clients
Integration:
- Tests routes, services, auth, tenancy
What: Database schema migration tool.
Responsibilities:
- Migration scripts (
versions/) - Alembic environment config (
env.py) - Templates for migrations
Integration:
- Reflects
models/for schema changes
└── frontend
├── Dockerfile
├── README.md
├── components.json
├── eslint.config.js
├── index.html
├── package-lock.json
├── package.json
├── postcss.config.js
├── public
│ └── vite.svg
├── src
│ ├── api
│ │ ├── apiClient.ts
│ │ ├── auth.ts
│ │ ├── chatbot.ts
│ │ ├── organization.ts
│ │ └── workspace.ts
│ ├── components
│ │ ├── App
│ │ │ └── App.tsx
│ │ ├── auth
│ │ ├── common
│ │ ├── dashboard
│ │ └── ui
│ │ └── button.tsx
│ ├── contexts
│ │ ├── AuthContext.tsx
│ │ ├── TenantContext.tsx
│ │ └── index.tsx
│ ├── hooks
│ │ ├── useAuth.ts
│ │ └── useTenant.ts
│ ├── lib
│ │ └── utils.ts
│ ├── main.tsx
│ ├── pages
│ │ ├── Dashboard.tsx
│ │ ├── LoginPage.tsx
│ │ └── OrgSwitchPage.tsx
│ ├── routes
│ │ └── PrivateRoute.tsx
│ ├── styles
│ │ └── index.css
│ └── utils
│ └── permissions.ts
├── tailwind.config.js
├── tsconfig.app.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts
Static assets like HTML, favicon, and manifest files.
React app source code.
- App.tsx / index.tsx: Entry points setting up providers and routing.
Axios clients for backend communication.
auth.ts: login/signup/logout requestschatbot.ts: chatbot CRUDapiClient.ts: base axios with JWT headers
Reusable UI parts.
auth/: login/register formsdashboard/: org/workspace switcherscommon/: buttons, modals, loaders
Global state management using React Context.
AuthContext: JWT, user info, permissionsTenantContext: current org/workspace
Reusable React hooks.
useAuth.ts: auth actionsuseTenant.ts: tenant context management
Route components/screens.
LoginPage.tsxDashboard.tsxOrgSwitchPage.tsx
Route protection and navigation.
PrivateRoute.tsx: protects routes requiring auth
Central styles (CSS, Tailwind config).
Helpers like permission checks (hasPermission()).
| Frontend Component | Backend Component | Purpose |
|---|---|---|
| api/auth.ts | api/v1/routes/auth.py | Authentication API requests |
| AuthContext | JWT tokens | Stores user info and permissions |
| TenantContext | Auth/session switching | Tenant context switching |
| Axios client | Middleware | Sends JWT with each request |
| Permissions (utils) | permission_service.py | Frontend permission checks |
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
- All PRs require passing tests
- Code must pass linting (ruff for Python, eslint for TypeScript)
- Add tests for new features
- Update documentation as needed
- 🐛 Bug fixes - Check Issues
- ✨ New features - See Roadmap
- 📚 Documentation - Help improve docs
- 🌍 Translations - Add language support
- 🧪 Testing - Improve test coverage
- 🎨 UI/UX - Design improvements
📖 Full guidelines: CONTRIBUTING.md
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
Copyright 2025 PrivexBot
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
- GitHub Issues: Report bugs and request features
- GitHub Discussions: Ask questions and share ideas
- Discord: Join our community
- Technical Docs: docs/
- API Reference: API_REFERENCE.md
- FAQ: docs/technical-docs/FAQ.md
For enterprise support, custom development, or consulting:
- Email: support@privexbot.com
- Website: https://privexbot.com
- Multi-tenant architecture
- Form-based chatbot builder
- Visual chatflow builder
- Knowledge base with RAG
- Website widget
- Multi-auth support
- Lead capture
- Docker deployment
- Telegram integration
- Discord integration
- Production hardening
- Comprehensive testing
- WhatsApp Business integration
- Slack integration
- Analytics dashboard v2
- A/B testing for bots
- Multi-language support
- Advanced workflow nodes
- Zapier app integration
- Mobile app (React Native)
- On-premise deployment
- SSO integration (SAML, OAuth)
- Advanced RBAC
- Audit logs
- SLA monitoring
- High availability setup
- Multi-region deployment
- Compliance certifications
📖 See roadmap above for current development status
Built with amazing open-source technologies:
- FastAPI - Modern Python web framework
- React - UI library
- ReactFlow - Visual workflow builder
- Crawl4AI - Website scraping
- Unstructured - Document parsing
- Secret Network - Privacy-preserving computation
- shadcn/ui - Beautiful UI components
Special thanks to all contributors!
If you find PrivexBot useful, please consider giving it a star! ⭐
Built by the PrivexBot Team
Website • Documentation • Discord • Twitter