Architecture

At a Glance#

Temp-Number provisions temporary phone numbers, processes activations & payments, and surfaces inbound SMS across web and native clients. Core responsibilities are split across an API layer, client interfaces, and external integrations (Platfone Retail, Firebase, payment gateways).

Component Summary#

Source Repositories#

• temp-number-backend
• temp-number-web
• temp-number-ios
• temp-number-android

Architecture Diagram#

Data Flows#

Customer Signup#

1. Customer accesses Web or Mobile client.
2. Client requests Firebase Auth token.
3. Client sends token to Backend API for verification.
4. Backend creates customer record if new in MySQL.
5. Backend creates customer record in Platfone via Retail API.

Customer balance top-up#

1. Customer initiates top-up in Web or Mobile client.
2. Client requests Firebase Auth token.
3. Client sends token to Backend API for verification.
4. Backend creates payment intent via payment gateway API.
5. Client completes payment via gateway SDK/redirect.
6. Gateway calls Backend webhook on payment success.
7. Backend verifies webhook signature and marks payment as completed in MySQL.
8. Backend credits customer balance via Platfone Retail API.

Number Activation & SMS Retrieval#

1. Customer requests number (country + service).
2. Backend authenticates (Firebase token) and reserves number via Platfone Retail API.
3. Number and activation id returned to client.
4. Client periodically polls Backend for new SMS messages.
5. Client shows SMS message to customer once received.

Technology Choices & Rationale#

• AdonisJS + TypeScript: Opinionated structure & validation reduce boilerplate; TypeScript improves reliability.
• Vue 3 + Vite: Fast HMR, Composition API granularity, ecosystem maturity (Pinia, i18n).
• MySQL 8.0: Transactions + indexing; easy replication path.
• Firebase Auth / FCM: Outsourced auth & push messaging across platforms.
• Multiple Gateways: Strategy abstraction isolates gateway differences.

Security & Authentication#

• Verify Firebase token each request.
• Rate limit provisioning endpoints (per IP & user).
• Validate signed payment webhooks.
• Sanitize SMS content on render.
• Restrict CORS origins to configured frontends.

Scalability & Performance#

• Stateless API horizontally scales behind load balancer.
• Polling acceptable initially; Platfone webhooks can be added later.
• CDN used for Web App assets.

Deployment Modes#

Local Docker and Google Cloud. Additional targets (Kubernetes, AWS) can be added without structural changes.

Windows WSL provided for deployment on Windows systems.

Setup Wizard automates prerequisite configuration and deployment, and reduces human error during manual setup.

Tech Stack#

Backend#

• Framework: AdonisJS (Node.js)
• Language: TypeScript
• Database: MySQL 8.0+ / MariaDB 10.6+
• Authentication: Firebase Auth
• Payments: Stripe, PayPal, Crypto, In-App Purchases, and more

https://github.com/platfone-com/temp-number-backend

Web Frontend#

• Framework: Vue 3 (Composition API)
• Build Tool: Vite
• Styling: Tailwind CSS v4
• State: Pinia
• i18n: Vue I18n

https://github.com/platfone-com/temp-number-web

iOS example app#

• Language: Swift
• UI Framework: UIKit
• Authentication: Firebase Auth

https://github.com/platfone-com/temp-number-ios

Android example app#

• Language: Kotlin
• Platform: Android SDK 34, minSdk 28
• Authentication: Firebase Auth

https://github.com/platfone-com/temp-number-android

Prerequisites#

Before deploying, ensure you have:

• Platfone Account: Sign up at platfone.com for API access
• Firebase Project: For authentication and notifications
• Payment Gateway: Stripe account or other supported gateways
• Hosting: Docker-compatible server or Google Cloud account

Next Steps#

Ready to get started?