phone-verif.comTechnical Deep Dive: Building a Modern Phone Verification System
A comprehensive look at the architecture, technologies, and engineering decisions behind our phone verification platform. Explore the backend infrastructure, API design, security considerations, and real-time verification flow.
System Overview
Our phone verification system is built on a modern, scalable architecture that combines the power of Supabase for backend services, Vonage for telecommunications infrastructure, and a React-based frontend with real-time capabilities. The system can handle thousands of verification requests with sub-second response times and 99.9% uptime.
Frontend Stack
- React 18 - Component-based UI with concurrent features
- TypeScript - Type-safe development
- Vite - Fast development and optimized builds
- Tailwind CSS - Utility-first styling with custom design system
- Framer Motion - Smooth animations and transitions
- React Query - Server state management and caching
Backend Stack
- Supabase - PostgreSQL database with real-time subscriptions
- Supabase Edge Functions - Serverless Deno runtime for API endpoints
- Supabase Row Level Security - Database-level access control
- Vonage API - Telecommunications infrastructure
- Vonage Cloud Runtime - Hosted scalable high performance backend services
- Stripe - Payment processing and subscription management
Reverse OTP Architecture
The core innovation of our system is the "Reverse OTP" flow, which eliminates the need for users to manually enter verification codes. Instead, users scan a QR code with their phone and send a WhatsApp message to complete verification.
Verification Flow Steps
- Session Initialization: The client requests verification session via POST /start-verification This generates a unique validation token linked to a session ID, both stored in a redis database.
- WhatsApp Integration: A direct WhatsApp deep link is generated containing a pre-filled message with the token. This link can be presented as a QR code that directs to WhatsApp with a pre-filled message to our bot
- Phone Extraction: The Vonage hosted backend receives a webhook from WhatsApp and extracts the phone number from the WhatsApp message
- Validation: The system validates the phone number format and links it with the original session thanks to the verification token. The Frontend can check the verification status continuously
Database Schema Design
Supabase provides a robust PostgreSQL database with real-time capabilities, making it an ideal choice for our verification system. It serves as the backbone for the portal, and as a data store for user information, API keys, and their quotas. It is also used for logging purposes and analytics. Our PostgreSQL schema is designed for scalability, security, and performance. We use Row Level Security policies to ensure users can only access their own data, while service roles handle system operations.
Security Features
- Row Level Security: Users can only access their own verification sessions
- API Key Validation: All requests validated against API key
- Session Expiration: Automatic cleanup of expired verification sessions
- Rate Limiting: Built-in protection against abuse and spam
- Audit Logging: Comprehensive logging of all verification attempts
Security Architecture
Security is paramount in a phone verification system. We implement multiple layers of protection to prevent fraud, abuse, and unauthorized access. We use short lived validation tokens and short-term storage of the full scanned phone number with no listing capabilities. We do not keep any clear phone numbers and use stripped version for analytics purpose and debugging.
Performance & Scalability
Our system is designed to handle high-volume verification requests with minimal latency. We achieve this through careful architectural choices and optimization strategies.
Performance Metrics
Scaling Considerations
As verification volume grows, our architecture scales horizontally through:
- • Automatic Edge Function scaling
- • Webhook queue processing
- • Load balancing across regions
- • Automatic scaling of Vonage's instances
Integration & API Design
Our REST API is designed for simplicity and reliability. Developers can integrate phone verification into their applications with just a few API calls.
API Endpoints
/start-verificationInitialize a new verification session
/check-verification-status/{session_id}Check verification status in real-time
Session & Token Management
Our verification system uses a sophisticated session and token management system to ensure security, track progress, and prevent abuse. Each verification request creates a unique session with multiple tracking points throughout the user journey.
Session Lifecycle
1. Session Creation
When a verification request is initiated, the system generates:
- • Session ID: Unique UUID for tracking the verification attempt
- • Validation Token: Cryptographically secure token embedded in QR code
- • Expiration Time: 15-minute window for completion
2. Token Validation
The validation token serves multiple purposes: authenticating the WhatsApp message, preventing replay attacks, and linking the phone number to the correct session. Tokens are single-use and expire automatically.
Verification Status States
The verification system tracks detailed status information throughout the user journey, providing real-time feedback and enabling precise analytics on user behavior and conversion rates.
Status Progression
pending
Initial state when verification session is created. QR code is generated but not yet scanned.
qr_code_scanned
User has scanned the QR code with their device. Tracking URL has been accessed.
whatsapp_previewed
WhatsApp has been opened and the message has been previewed, but not yet sent.
opened
WhatsApp conversation has been fully opened, message is ready to be sent.
verified / sms_validated
Phone number has been successfully extracted and validated. Verification complete.
expired / failed
Session has expired (15 min timeout) or failed due to invalid token/phone number.
WhatsApp Preview & QR Code Tracking
Advanced tracking mechanisms monitor user interaction at every step of the verification process, providing detailed analytics on user behavior and helping optimize conversion rates.
QR Code Scan Detection
Tracking URL Generation
Each QR code contains a unique tracking URL that logs the scan event before redirecting to WhatsApp:
https://t.phone-verif.com/t/{validation_token}?sid={session_id}WhatsApp State Tracking
Preview Detection
WhatsApp calls our tracking URL when generating link previews, allowing us to detect when the message is being composed but not yet sent.
- • User-Agent Analysis: Detect WhatsApp preview bots vs. real users
- • Timing Analysis: Distinguish between preview and actual access
- • IP Geolocation: Verify geographic consistency
Conversion Funnel Analytics
Typical conversion rates from QR code generation to successful verification
Future Roadmap
We're continuously improving the platform with new features and optimizations.
Get Started
Ready to integrate phone verification into your application? Our API is designed for developers, with comprehensive documentation and SDKs for popular programming languages.