Transform your doorbell into an intelligent visitor identification system with advanced face recognition, multi-provider AI analysis, and comprehensive visitor insights.

Click any screenshot to view full size

🏠 Main Dashboard Real-time visitor monitoring with AI-powered insights	🤖 AI Provider Configuration Choose from 5 different AI providers for optimal performance
📊 AI Analytics & Insights Track costs, performance, and usage across all AI providers	👤 Face Recognition Settings Advanced face detection and visitor identification

🧠 Multi-Provider AI Intelligence - Choose from 5 AI providers (OpenAI, Claude, Gemini, Google Cloud Vision, Ollama)
👤 Advanced Face Recognition - Identify and track recurring visitors automatically
📱 Mobile-Optimized Experience - Native-like mobile interface with pull-to-refresh
📊 Comprehensive Analytics - Track AI usage, costs, and visitor patterns with export capabilities
🔒 Privacy-First Design - Self-hosted solution that keeps your data secure
⚡ Real-Time Updates - WebSocket-powered live notifications and dashboard

Get up and running in under 5 minutes:

• 🐳 Docker and Docker Compose
• 💾 At least 2GB free disk space
• 🌐 Internet connection for initial build

# Clone the repository
git clone https://github.com/Beast12/who-rang.git
cd who-rang

# Build and start the containers (first run will take a few minutes)
docker-compose up -d --build

# Access your dashboard
open http://localhost:8080

That's it! 🎉 Your AI-powered doorbell dashboard is ready.

📖 Need help? Check our Installation Guide for detailed setup instructions.

• ⏱️ Initial build takes 3-5 minutes to download dependencies and build containers
• 🔄 Subsequent starts are much faster (under 30 seconds)
• 📊 Dashboard will be available at http://localhost:8080
• 🔌 API will be available at http://localhost:3001

WhoRang supports 5 different AI providers - choose what works best for you:

• 🎯 Intelligent Scene Analysis - Comprehensive visitor and object detection
• 👥 Face Recognition & Tracking - Automatically identify recurring visitors
• 📈 Usage Analytics - Track AI costs, performance, and accuracy across providers
• 📄 Export Reports - Generate CSV/PDF analytics reports
• 🔄 Real-Time Processing - Instant AI analysis of doorbell events

Built from the ground up for mobile devices:

• 📱 Native-like Interface - Optimized for touch interactions
• 🔄 Pull-to-Refresh - Intuitive mobile gestures
• 📊 Mobile Analytics - Responsive charts and statistics
• 🎛️ Touch-Friendly Controls - Large buttons and easy navigation
• ⚡ Fast Performance - Optimized for mobile networks

Get deep insights into your doorbell activity:

• 📈 Daily, weekly, and monthly visitor trends
• 🕐 Peak activity time analysis
• 🌍 Location-based visitor tracking
• 🌤️ Weather correlation insights

• 💰 Real-time cost monitoring across all AI providers
• ⚡ Response time and accuracy metrics
• 📊 Provider comparison analytics
• 📈 Usage optimization recommendations

• 📄 PDF Reports - Professional analytics summaries
• 📊 CSV Data - Raw data for further analysis
• 🔄 Automated Exports - Schedule regular reports

Built with cutting-edge technologies:

• ⚛️ React 18 + TypeScript - Modern, type-safe development
• ⚡ Vite - Lightning-fast build tool
• 🎨 Tailwind CSS + shadcn/ui - Beautiful, responsive design
• 📱 Mobile-First - Responsive across all devices
• 🔄 React Query - Efficient server state management

• 🟢 Node.js + Express - Robust server architecture
• 🗄️ SQLite - Lightweight, reliable database
• 🔌 WebSocket - Real-time communication
• 🤖 Multi-AI Integration - Unified AI provider interface

• 🐳 Docker - One-command deployment
• 🌐 Nginx - Production-ready web server
• 🔒 Security - Built-in security best practices

Your data stays yours:

• 🔒 Self-Hosted - Complete control over your data
• 🏠 Local Processing - Option to use local AI (Ollama)
• 🛡️ No Cloud Dependencies - Works entirely offline (with local AI)
• 🔐 Secure by Default - Built with security best practices

Comprehensive guides to get you started:

• 📖 Installation Guide - Step-by-step setup
• ⚙️ Configuration - Customize your setup
• 🏠 Home Assistant Integration - Connect with Home Assistant
• 🔌 API Reference - Complete API documentation
• 🚀 Deployment - Production deployment guide
• 🔧 Troubleshooting - Common issues and solutions

Perfect for:

• 🏠 Smart Home Enthusiasts - Integrate with Home Assistant
• 🔒 Security-Conscious Users - Monitor and analyze visitor patterns
• 👨‍💻 Developers - Extensible AI-powered platform
• 📊 Data Lovers - Rich analytics and insights
• 🏢 Small Businesses - Track customer visits and patterns

If you find WhoRang useful, consider supporting its development:

Or scan the QR code:

Your support helps maintain and improve WhoRang!

We welcome contributions from the community! Please read our Contributing Guide for detailed information on how to get started.

Quick Start for Contributors:

• 🍴 Fork the repository and create a feature branch from develop
• 🧪 Test your changes locally with docker-compose up -d --build
• 📝 Follow our Pull Request Template
• ✅ Ensure all CI checks pass (automated testing via GitHub Actions)

Types of Contributions:

• 🐛 Bug Reports & Fixes - Help us improve stability
• 💡 Feature Requests & Implementation - Share your ideas
• 🔧 Code Contributions - Submit pull requests to develop branch
• 📖 Documentation - Improve our guides and examples

This project is open source and available under the MIT License.