A production-grade SMS verification platform that aggregates multiple SMS provider APIs, providing virtual phone numbers for receiving SMS verification codes — with a full-featured admin dashboard and a polished user mobile application.

StroApp SMS is a SMS-PaaS (SMS Platform as a Service) that solves the problem of needing a real phone number to receive SMS verification codes. Users purchase virtual numbers to receive OTP/activation codes for services like WhatsApp, Telegram, Google, Facebook, TikTok, and hundreds more — without exposing their personal phone number.

The platform aggregates supply from multiple SMS provider APIs, applies a configurable markup engine for profitability, and delivers a unified experience through:

• 📱 User Mobile App (Flutter) — Browse services, purchase numbers, receive SMS, manage account
• 🛠️ Admin Dashboard (Flutter) — Manage users, orders, finances, security, and platform configuration
• ⚙️ Backend API (Python/FastAPI) — RESTful API powering both frontends with enterprise-grade security

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User App      │     │   Admin App     │     │  3rd-Party      │
│  (Flutter)      │     │  (Flutter)      │     │  Integrations   │
│  port 3000      │     │  port 3001      │     │  (OAuth, IAP,   │
└────────┬────────┘     └────────┬────────┘     │  Payments...)   │
         │                       │              └────────┬────────┘
         └───────────┬───────────┘                       │
                     │ HTTP/JSON                         │
                     ▼                                   │
            ┌────────────────┐                            │
            │   FastAPI App  │◄───────────────────────────┘
            │   Port 9527    │
            │  + Gunicorn    │
            └───────┬────────┘
                    │
         ┌──────────┼──────────┐
         ▼          ▼          ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │PostgreSQL│ │  Redis  │ │ SMS     │
   │ Database │ │  Cache  │ │Providers│
   │ :5433    │ │ :6379   │ │(4 APIs) │
   └─────────┘ └─────────┘ └─────────┘

1. User opens the mobile app, browses available services and countries
2. Backend queries provider APIs for real-time pricing and stock
3. Price Engine applies markup rules, user-specific pricing, and coins conversion
4. User purchases a number → coins deducted → provider API called → number allocated
5. Polling Service monitors the number for incoming SMS messages
6. Delivery — SMS code is delivered to the user via app UI, webhook, email forwarding, or Telegram bot
7. Optional — Order auto-cancels after timeout with refund

User Features

• Email/password authentication with JWT (access + refresh tokens)
• Google Sign-In and Apple Sign-In OAuth integration
• Multi-factor authentication (TOTP)
• Virtual number purchase for SMS verification (temporary & rental)
• Real-time SMS message polling with auto-refresh
• Number cancellation with partial refund
• Wallet system with coin-based transactions
• In-app purchase payments (Google Play, Apple App Store, Stripe)
• Webhook management for SMS delivery callbacks
• Email forwarding and Telegram bot integration
• Multi-tier subscription plans (Freemium, PAYG, Pro, Custom)
• Temporary email inbox service
• Voice call verification (call & speak code)
• Referral and affiliate programs
• Reseller and white-label support
• KYC verification and compliance
• GDPR data export and account deletion

Admin Features

• Admin authentication and session management
• User management (CRUD, ban, coin adjustment, tier change)
• Order and transaction monitoring
• Provider management (enable/disable, balance check)
• Service management (activate/deactivate)
• Dynamic pricing engine with markup rules
• Pricing templates and user-specific pricing
• Support ticket system
• Dispute resolution
• KYC document verification
• Revenue and P&L reporting
• Financial reconciliation
• Provider settlement tracking
• Affiliate commission management
• Reseller account management
• Broadcast push notifications
• Security scanning and compliance reporting
• Automated database backup and disaster recovery
• Audit logging (enterprise-grade)
• Feature flag management
• Email template customization
• Data export (users, transactions, payments, audit logs)
• Security scans, secrets check, compliance reports
• Multi-language support (7 languages)

Security & Compliance

• Rate limiting (Redis token bucket)
• CSRF protection
• XSS prevention
• SQL injection prevention (ORM-based)
• Proxy/VPN detection middleware
• Device fingerprinting
• IP blacklisting
• PII masking in logs
• Structured JSON logging
• Sentry error tracking
• Prometheus metrics
• Security headers (HSTS, CSP, X-Frame-Options, etc.)

• Browse 100+ services organized by category
• View prices across 200+ countries
• Purchase numbers with one tap (from presets)
• Real-time SMS waiting screen with countdown timer
• Order history with full details
• Wallet with top-up via Google Pay / Apple Pay
• Number rental with duration and auto-extend
• Temporary email inbox
• Voice verification purchase
• Saved presets for quick re-purchase
• Webhook and forwarding configuration
• MFA setup and management
• API key management
• Active sessions management
• Affiliate dashboard with commissions and payouts
• KYC document submission and status tracking
• Support ticket system
• Multi-language (Arabic/English) with RTL support
• Dark/Light theme
• Biometric authentication (fingerprint, face ID)
• Deep linking (referral codes)
• Push notifications via Firebase Cloud Messaging
• Onboarding wizard for new users

• Dashboard with KPI cards and charts (new users, orders, revenue)
• User management with search, filters, and bulk actions
• Order and transaction browsing with detail views
• Support ticket management with reply thread
• System settings (coins per USD, markup, email limits)
• Provider and service management
• Pricing engine with templates, promotions, and markup rules
• Affiliate applications, commissions, and payouts
• Reseller accounts and credit allocation
• Financial reports (revenue, costs, settlements, tax)
• P&L reports
• Analytics dashboard with verification stats and carrier analytics
• Ledger and reconciliation tools
• Security screen: vulnerability scans, secrets check, compliance
• Backup management: create, list, restore
• Disaster recovery: run tests, monitor status
• Webhook queue and retry monitoring
• Broadcast push notifications
• Blacklist management (IP, tokens)
• Whitelabel domain management
• Data sync orchestrator with markup rules
• Data export (CSV) for users, transactions, payments, audit logs
• Telegram bot connection management
• Feature flag toggling
• Session management with force logout
• Email template editing
• Waitlist management
• Multi-language support (7 languages)

stroapp-sms/                          # Monorepo root
├── app/                              # Python backend package
│   ├── api/
│   │   ├── v1/                       # Version 1 API (60+ route files)
│   │   │   ├── auth.py               # Authentication endpoints
│   │   │   ├── purchase.py           # SMS purchase & orders
│   │   │   ├── services.py           # Service listing
│   │   │   ├── user.py               # User profile & balance
│   │   │   ├── payments.py           # Payment processing
│   │   │   ├── webhooks.py           # Webhook management
│   │   │   ├── admin_*.py            # 14 admin sub-modules
│   │   │   └── ...                   # 40+ more endpoint files
│   │   └── v4/                       # Version 4 API (clean admin)
│   │       └── admin.py              # Unified admin API
│   ├── core/                         # Framework & shared utilities
│   │   ├── config.py                 # Pydantic Settings
│   │   ├── database.py               # SQLAlchemy setup
│   │   ├── security.py               # JWT, hashing
│   │   ├── dependencies.py           # FastAPI dependencies
│   │   └── middleware.py             # Custom ASGI middleware
│   ├── domain/
│   │   ├── models.py                 # 60+ SQLAlchemy models
│   │   └── coins.py                  # Coin conversion logic
│   ├── infrastructure/
│   │   ├── providers/                # SMS provider adapters
│   │   │   ├── base.py               # Abstract provider
│   │   │   ├── router.py             # Provider router (fallback)
│   │   │   ├── smsman.py             # SMS-Man integration
│   │   │   ├── fivesim.py            # 5sim integration
│   │   │   ├── smsactivate.py        # SMS-Activate integration
│   │   │   ├── smspool.py            # SMSPool integration
│   │   │   └── circuit_breaker.py    # Fault tolerance
│   │   ├── payments/                 # Payment integrations
│   │   ├── cache/                    # Redis caching
│   │   ├── queue/                    # Webhook queue (Redis streams)
│   │   ├── push/                     # OneSignal push
│   │   ├── bot/                      # Telegram bot
│   │   └── security/                 # Secrets & compliance
│   ├── middleware/                    # HTTP middleware
│   ├── schemas/                      # Pydantic schemas
│   ├── services/                     # Business logic (40+ files)
│   │   ├── purchase_service.py       # SMS purchase flow
│   │   ├── price_calculator.py       # Pricing engine
│   │   ├── pricing_engine_service.py # User-specific pricing
│   │   ├── payment_service.py        # Payment processing
│   │   ├── audit_service.py          # Enterprise audit
│   │   ├── backup_service.py         # DB backup/restore
│   │   ├── security_scanner.py       # Security scanning
│   │   ├── background.py             # Background workers
│   │   └── ...                       # 30+ more services
│   └── websocket/                    # WebSocket manager
├── infrastructure/
│   └── db/
│       └── migrations/               # Alembic migrations
├── scripts/                          # Utility scripts
│   ├── seed_admin.py                 # Create admin user
│   ├── backup.sh                     # Database backup
│   └── run_security_audit.sh         # Security audit
├── main.py                           # Application entry point
├── Dockerfile                        # Docker build
├── docker-compose.yml                # Full stack setup
├── nginx.conf                        # Production proxy config
├── requirements.txt                  # Python dependencies
├── .env.example                      # Example environment
│
├── stroapp-sms-user/                 # User Flutter app
│   └── lib/
│       ├── main.dart                 # App entry point
│       ├── core/                     # API, models, router, theme
│       └── features/                 # Feature modules
│           ├── sms_purchase/         # SMS buying flow
│           ├── auth/                 # Authentication
│           ├── home/                 # Dashboard
│           ├── wallet/               # Wallet & payments
│           ├── settings/             # Settings hub
│           ├── presets/              # Saved presets
│           ├── temp_email/           # Temp email inbox
│           ├── voice/                # Voice verification
│           ├── rentals/              # Number rental
│           └── ...                   # 10+ more features
│
└── stroapp-sms-admin/                # Admin Flutter app
    └── lib/
        ├── main.dart                 # App entry point
        ├── app/                      # Screens & tabs
        │   ├── screens/              # 21 screen files
        │   └── tabs/                 # 5 bottom nav tabs
        └── core/                     # API, models, services, theme
            ├── api_constants.dart    # 184 API endpoint definitions
            ├── services/             # 5 service classes
            ├── models/               # Data models
            └── widgets/              # 12 reusable widgets

• Python 3.12+
• PostgreSQL 16
• Redis 7
• Flutter 3.x (for mobile apps)
• Docker (optional, for containerized deployment)

git clone <repo-url> stroapp-sms
cd stroapp-sms

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your settings (database URL, API keys, secrets)

# Using Docker (recommended for development)
docker run -d \
  --name stroapp-db \
  -e POSTGRES_USER=stroapp \
  -e POSTGRES_PASSWORD=stroapp_pass \
  -e POSTGRES_DB=stroapp \
  -p 5433:5432 \
  postgres:16

# Run migrations
alembic upgrade head

# Seed admin user
python scripts/seed_admin.py admin@example.com your-password

# Development
python main.py

# Production (with Gunicorn)
gunicorn main:app -c gunicorn.conf.py

The API will be available at http://localhost:9527/stroapp/docs (Swagger UI).

cd stroapp-sms-user
cp .env.example .env  # edit API_BASE_URL
flutter pub get
flutter run -d chrome  # or -d android, -d ios

cd stroapp-sms-admin
flutter pub get
flutter run -d chrome  # or -d android, -d ios

docker compose up -d

This starts PostgreSQL, Redis, and the FastAPI application together.

Full list available in .env.example.

Each Flutter app uses a .env file for configuration:

User App (.env):

API_BASE_URL=http://localhost:9527/stroapp/v1
CONNECT_TIMEOUT=10000
RECEIVE_TIMEOUT=15000

Admin App: Base URL is configured in lib/core/constants/api_constants.dart and can be changed at runtime via the login screen UI.

• User API: /stroapp/v1/...
• Admin API: /stroapp/v4/admin/api/...
• Swagger UI: /stroapp/docs
• ReDoc: /stroapp/redoc
• Health: /health
• Metrics: /stroapp/metrics

• User: JWT Bearer tokens (access + refresh tokens)
• Admin: JWT Bearer tokens (separate admin login endpoint)
• MFA: Optional TOTP with x-mfa-token header
• API Keys: nsk_ prefixed keys for programmatic access

All API responses follow a consistent structure:

{
  "success": true,
  "data": { ... },
  "error": null,
  "request_id": "uuid"
}

Paginated responses:

{
  "success": true,
  "data": { "items": [...], "total": 100, "page": 1, "per_page": 20 },
  "error": null
}

The platform implements multiple layers of security:

• Rate Limiting: Redis token bucket algorithm (configurable limits)
• CSRF Protection: Token-based per-session
• XSS Prevention: Input sanitization and output encoding
• SQL Injection: ORM-based queries + statement-level protection
• Proxy/VPN Detection: Middleware to flag anonymous traffic
• Device Fingerprinting: Risk scoring per device
• IP Blacklisting: Manual and automated blacklist management
• Session Management: Active session tracking with revocation
• MFA: Optional TOTP two-factor authentication
• Audit Logging: Every admin action is logged with user, IP, timestamp
• Security Scanning: Automated vulnerability scanning
• Secrets Management: Encrypted storage of sensitive configuration
• GDPR Compliance: Data export, deletion, and consent management
• KYC/AML: Identity verification for high-value accounts
• WAF: NGINX-based web application firewall in production
• HTTPS: SSL/TLS enforcement via NGINX

# Backend tests
pytest tests/ -v

# Run specific test
pytest tests/test_comprehensive.py -v

# Flutter tests (user app)
cd stroapp-sms-user
flutter test

# Flutter tests (admin app)
cd stroapp-sms-admin
flutter test

Internet → NGINX (Reverse Proxy + WAF) → Gunicorn (4 workers) → FastAPI
                                                                    │
                                    PostgreSQL ←────────────────────┤
                                    Redis ←────────────────────────┤
                                    SMS Providers ←────────────────┘

# Build and run
docker compose up -d --build

# Check logs
docker compose logs -f api

# Run migrations
docker compose exec api alembic upgrade head

# Create admin user
docker compose exec api python scripts/seed_admin.py admin@example.com password

1. Set up PostgreSQL and Redis
2. Configure .env with production values
3. Run with Gunicorn:

   gunicorn main:app -c gunicorn.conf.py

4. Set up NGINX reverse proxy using nginx.conf
5. Configure SSL certificates (Let's Encrypt)
6. Set up monitoring (Sentry, Prometheus)
7. Configure automated backups via the admin panel

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

• Follow existing code style and conventions
• Write tests for new features
• Update API documentation for endpoint changes
• Run pytest before submitting PRs
• Use conventional commit messages

All rights reserved. This project is proprietary software.

• Author: Omer Jasim — oj33593@gmail.com
• API Docs: /stroapp/docs (Swagger), /stroapp/redoc (ReDoc)
• Admin Panel: Accessible via the admin Flutter app
• Issues: Report via GitHub Issues
• Security: Report via Security Advisories