🔐 OTP Verification System

A production-ready One-Time Password (OTP) verification system using phone call bot technology. Users receive automated phone calls that ask for OTP codes, with entered digits appearing in real-time on a modern web dashboard.

✨ Features

📞 Phone Call Bot

• Automated call initiation via Twilio
• Natural voice prompts (Polly.Joanna)
• DTMF (touch-tone) digit collection
• Call retry logic with exponential backoff
• Multi-language support ready

📊 Real-time Dashboard

• Live digit display as user enters code
• Call status monitoring
• Verification status tracking
• Modern, cyberpunk-inspired UI
• Fully responsive design

🔒 Security

• End-to-end encrypted communications
• Rate limiting (Redis-based)
• OTP expiration (configurable)
• Webhook signature validation
• SQL injection prevention
• CSRF protection

📈 Monitoring

• Comprehensive metrics dashboard
• Call success rates
• Verification analytics
• System health monitoring
• Structured JSON logging

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│                 │     │                 │     │                 │
│    Frontend     │────▶│    Backend      │────▶│    Twilio       │
│    (React)      │     │   (FastAPI)     │     │    API          │
│                 │◀────│                 │◀────│                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │                       │                       │
        │               ┌───────┴───────┐               │
        │               │               │               │
        ▼               ▼               ▼               ▼
  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
  │WebSocket │   │PostgreSQL│   │  Redis   │   │ Webhook  │
  │Real-time │   │ Database │   │  Cache   │   │ Callback │
  └──────────┘   └──────────┘   └──────────┘   └──────────┘

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Twilio Account (Sign up free)
• Node.js 18+ (for local development)
• Python 3.12+ (for local development)

1. Clone & Configure

# Clone the repository
git clone https://github.com/your-repo/otp-verification-system.git
cd otp-verification-system

# Copy environment template
cp env.example .env

# Edit .env with your settings
# IMPORTANT: Set your Twilio credentials

2. Configure Twilio

1. Get your credentials from Twilio Console
2. Update .env:

   TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   TWILIO_AUTH_TOKEN=your-auth-token-here
   TWILIO_PHONE_NUMBER=+1234567890
   TWILIO_WEBHOOK_BASE_URL=https://your-domain.com
   

3. Start with Docker

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Access the dashboard
open http://localhost:3000

4. Local Development

# Backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend (new terminal)
cd frontend
npm install
npm run dev

📁 Project Structure

otp-verification-system/
├── backend/
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── core/          # Config, security, logging
│   │   ├── db/            # Database & Redis
│   │   ├── models/        # SQLAlchemy models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   └── main.py        # Application entry
│   ├── tests/             # Test suite
│   ├── migrations/        # Database migrations
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── hooks/         # Custom hooks
│   │   ├── pages/         # Page components
│   │   ├── services/      # API service
│   │   └── styles/        # CSS styles
│   ├── Dockerfile
│   └── package.json
├── nginx/                 # Nginx configuration
├── docker-compose.yml
├── Makefile
└── README.md

🔌 API Reference

OTP Endpoints

Method	Endpoint	Description
POST	/api/v1/otp/request	Request OTP verification call
POST	/api/v1/otp/verify	Verify OTP code
GET	/api/v1/otp/status/{session_id}	Get verification status
DELETE	/api/v1/otp/cancel/{session_id}	Cancel OTP session

WebSocket

Connect to /ws/otp/{session_id} for real-time updates:

const ws = new WebSocket('ws://localhost:8000/ws/otp/SESSION_ID');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.event) {
    case 'digit_received':
      console.log(`Digit ${data.data.digit} at position ${data.data.position}`);
      break;
    case 'verification_complete':
      console.log('Verified!', data.data.success);
      break;
  }
};

Example Request

# Request OTP call
curl -X POST http://localhost:8000/api/v1/otp/request \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+14155551234"}'

# Response
{
  "session_id": "abc123def456",
  "status": "calling",
  "message": "Initiating phone call...",
  "expires_at": "2024-01-15T10:30:00Z",
  "websocket_url": "ws://localhost:8000/ws/otp/abc123def456"
}

📖 Full Documentation

• API Documentation: http://localhost:8000/docs (Swagger UI)
• ReDoc: http://localhost:8000/redoc

🔧 Configuration

Environment Variables

Variable	Description	Default
APP_ENV	Environment (development/production)	development
APP_SECRET_KEY	Secret key for JWT	-
DATABASE_URL	PostgreSQL connection URL	-
REDIS_URL	Redis connection URL	-
TWILIO_ACCOUNT_SID	Twilio Account SID	-
TWILIO_AUTH_TOKEN	Twilio Auth Token	-
TWILIO_PHONE_NUMBER	Twilio phone number	-
OTP_LENGTH	Number of OTP digits	6
OTP_EXPIRY_MINUTES	OTP validity period	10
OTP_MAX_ATTEMPTS	Max verification attempts	3

🧪 Testing

# Run backend tests
cd backend
pytest -v

# With coverage
pytest --cov=app --cov-report=html

# Run frontend tests
cd frontend
npm run test

🚢 Deployment

Docker Compose (Production)

# Build for production
docker-compose -f docker-compose.yml build

# Start services
docker-compose up -d

# Scale backend
docker-compose up -d --scale backend=3

Environment Setup

1. Set APP_ENV=production
2. Use strong APP_SECRET_KEY (32+ characters)
3. Configure proper CORS_ORIGINS
4. Set up SSL/TLS certificates
5. Configure Twilio webhook URL

📊 Monitoring

Health Checks

• /health - Comprehensive health check
• /health/live - Kubernetes liveness probe
• /health/ready - Kubernetes readiness probe

Metrics

Access /api/v1/metrics/ for:

• Call success rate
• Verification success rate
• Active sessions
• Error rate
• Hourly statistics

🔒 Security Best Practices

1. Never commit .env - Use environment variables in production
2. Rotate secrets regularly - Update API keys and tokens
3. Enable rate limiting - Prevent abuse
4. Use HTTPS - Encrypt all traffic
5. Validate webhooks - Verify Twilio signatures
6. Monitor logs - Set up alerting for anomalies

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI - Modern Python web framework
• Twilio - Cloud communications platform
• React - UI library
• TailwindCSS - Utility-first CSS

---

Built with ❤️ for secure verification