BluChat is a revolutionary Progressive Web App that enables secure, offline messaging through Bluetooth mesh networking. When the internet fails, BluChat keeps you connected with your peers through encrypted, peer-to-peer communication.
In our hyper-connected world, we often forget that connectivity isn't guaranteed. Natural disasters, network outages, or simply being in remote areas can cut us off from traditional messaging platforms. BluChat solves this by creating a resilient communication network that works entirely offline.
- 🔄 Offline-First: Works without internet connection
- 🔐 End-to-End Encryption: Messages secured with TweetNaCl cryptography
- 📡 Bluetooth Mesh: Multi-hop message routing through peer network
- ⚡ Progressive Web App: Install like a native app, works everywhere
- 🌐 Cross-Platform: Works on desktop, mobile, and tablets
- 🔒 Privacy-Focused: No servers, no data collection, no tracking
- Modern web browser with Bluetooth support (Chrome, Edge, Opera)
- Bluetooth-enabled device
- HTTPS connection (required for Web Bluetooth API)
- Visit the App: Navigate to the BluChat URL in your browser
- Install PWA: Click "Install" when prompted, or use your browser's install option
- Enable Bluetooth: Grant Bluetooth permissions when requested
- Start Chatting: Create or join channels and start messaging!
# Clone the repository
git clone https://github.com/ali-master/bluchat.git
cd bluchat
# Install dependencies
pnpm install
# Start development server
pnpm dev
# Build for production
pnpm build- Multi-Channel Support: Create and join different conversation channels
- Real-Time Messaging: Instant message delivery between connected peers
- Message Persistence: Offline storage using IndexedDB
- Channel Security: Password-protected private channels
- End-to-End Encryption: All messages encrypted with industry-standard cryptography
- Perfect Forward Secrecy: Unique keys for each session
- No Central Server: Completely decentralized architecture
- Local Data Only: All data stored locally on your device
- Bluetooth Low Energy: Efficient power consumption
- Mesh Networking: Messages route through multiple peers
- Auto-Discovery: Automatic peer detection and connection
- Connection Management: Smart reconnection and peer management
- Modern UI: Clean, responsive interface built with shadcn/ui
- Dark/Light Mode: Automatic theme switching
- Mobile-First: Optimized for touch devices
- Offline Indicators: Clear connection status feedback
-
Core Infrastructure
- Progressive Web App setup with service workers
- Bluetooth Web API integration
- React + TypeScript foundation
- Zustand state management
-
Messaging System
- Real-time peer-to-peer messaging
- Multi-channel support with hashtag naming
- Message persistence with IndexedDB
- TTL-based message routing and auto-relay
- Message fragmentation for large content
- LZ4 compression optimization
-
Security & Cryptography
- X25519 key exchange protocol
- Ed25519 digital signatures
- End-to-end encryption with TweetNaCl
- Scrypt-based key derivation for channels
- Perfect Forward Secrecy implementation
- Message signing and verification
-
Bluetooth Mesh Networking
- Dual central/peripheral mode support
- Mesh topology with routing tables
- Multi-hop message forwarding
- Duplicate prevention with message ID tracking
- Network discovery and peer announcements
- Dynamic UUID generation and management system
- Persistent UUID storage with sharing capabilities
- Proper Bluetooth service identification
-
Privacy Features
- Ephemeral identity rotation (2-hour cycles)
- Cover traffic generation
- Timing randomization
- Message padding for uniform sizes
- Anonymity set management
-
Channel Management
- State machine (Discovery → Join → Auth → Active)
- Hashtag-based channel naming (#channelname)
- Owner privileges and access control
- Password-protected private channels
- Automatic channel discovery
-
User Interface
- Modern responsive design
- shadcn/ui component library
- Dark/light theme toggle with persistence
- Mobile-optimized interface
- Real-time connection status indicators
- Confirm dialogs replacing browser prompts
-
Protocol & Performance
- Optimized binary packet structure (32-byte header)
- Efficient message encoding with relative timestamps
- Smart compression (only when beneficial)
- Battery-aware operation patterns
- Advanced background scanning optimization with Battery API
- Service Worker mesh coordination with cross-tab communication
- Predictive mesh health monitoring and auto-recovery
- Intelligent scan frequency and power adaptation
-
Developer Experience
- TypeScript strict mode
- ESLint + Prettier configuration
- Vite build system with HMR
- Modular service architecture
- Web Platform Enhancements
- Complete message fragment reassembly logic
- WebRTC fallback for connectivity
-
Advanced Messaging
- File sharing with automatic fragmentation
- Voice message recording and playback
- Message reactions and threaded replies
- Full-text message search
- Message backup/export with encryption
-
Network Features
- Wi-Fi Direct integration for higher bandwidth
- Hybrid mesh (Bluetooth + Wi-Fi + WebRTC)
- Bridge mode for connecting separate mesh networks
- Real-time network topology visualization
- Mesh health monitoring and diagnostics
-
User Experience
- Customizable user profiles with avatars
- Smart notifications with privacy preservation
- Typing indicators with timing obfuscation
- Read receipts with optional anonymity
- Advanced contact and peer management
-
Native Applications
- Electron desktop app with full BLE support
- React Native mobile app for true mesh networking
- Browser extension for web integration
- Command-line interface for server deployments
-
Developer Platform
- Plugin system for custom features
- REST API for third-party integrations
- Custom encryption protocol support
- Comprehensive network diagnostics toolkit
-
Enterprise Features
- Organization management
- Admin controls and moderation
- Compliance and audit logs
- Integration with enterprise systems
-
Research & Innovation
- Quantum-resistant cryptography
- AI-powered spam detection
- Advanced mesh routing protocols
- Emergency communication modes
- Frontend: React 18, TypeScript, Vite
- State Management: Zustand
- UI Components: shadcn/ui, Tailwind CSS
- Cryptography: TweetNaCl, Scrypt-JS
- Storage: IndexedDB
- Connectivity: Web Bluetooth API
- PWA: Workbox, Service Workers
| Browser | Desktop | Mobile | Notes |
|---|---|---|---|
| Chrome | ✅ | ✅ | Full support |
| Edge | ✅ | ✅ | Full support |
| Opera | ✅ | ✅ | Full support |
| Safari | ❌ | ❌ | No Web Bluetooth support |
| Firefox | ❌ | ❌ | No Web Bluetooth support |
While BluChat implements the full BitChat protocol specification, the web platform has inherent constraints:
- 🚫 True BLE Advertising: Web Bluetooth API doesn't support peripheral mode - limits mesh networking capabilities
- ⏱️ Background Scanning: Browser security policies restrict continuous background scanning
- 🧩 Fragment Reassembly: Basic framework implemented, full message reassembly logic needs completion
- ⚡ Native Performance: Web implementation has overhead compared to native BLE stack
💡 For Production Use: Consider native mobile/desktop implementations for optimal mesh networking performance.
BluChat takes security seriously:
- No Data Collection: We don't collect, store, or analyze any user data
- Local Storage: All data remains on your device
- Open Source: Code is publicly auditable
- Standard Cryptography: Uses well-established encryption libraries
- Regular Updates: Security patches and improvements
We welcome contributions from the community! Whether you're interested in:
- 🐛 Bug fixes and improvements
- ✨ New features and enhancements
- 📚 Documentation improvements
- 🎨 UI/UX enhancements
- 🔒 Security audits
Please see our Contributing Guide for details on how to get started.
- Code Quality: Follow TypeScript best practices
- Testing: Write tests for new features
- Documentation: Update docs for user-facing changes
- Security: Consider security implications of all changes
MIT License - see LICENSE file for details.
BluChat is inspired by the BitChat project and built upon the shoulders of many open-source projects:
- TweetNaCl for cryptography
- React for the UI framework
- shadcn/ui for beautiful components
- Zustand for state management
Built with ❤️ by Ali Torki for a more connected world