# supremeanalytics-limited/numvault architecture

> Architecture diagram of the GitHub repository supremeanalytics-limited/numvault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supremeanalytics-limited/numvault
- Repository: https://github.com/supremeanalytics-limited/numvault

## Overview

NumVault is a mobile app for buying temporary phone numbers to verify services, with wallet-based payments and refunds, order tracking, and a student referral-lead programme. The main customer journey is browse a service and country, purchase a number, then receive its verification code; users can also fund a wallet and track orders. The app delegates number-provider access and payment operations to backend services, while Supabase supports authentication and application data. The README documents refunds, payout review, and lead-program rules; their detailed wiring is not confirmed by the sampled source.

Main entry points: [`services/orderService.ts`](https://github.com/supremeanalytics-limited/numvault/blob/main/services/orderService.ts) (Order service), [`services/acquisitionService.ts`](https://github.com/supremeanalytics-limited/numvault/blob/main/services/acquisitionService.ts) (Acquisition service), [`app/(tabs)/index.tsx`](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/index.tsx) (Number catalog), [`app/(tabs)/wallet.tsx`](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/wallet.tsx) (Wallet screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_catalog["Number catalog<br/>[index.tsx]"]
  node_checkout["Checkout<br/>[checkout.tsx]"]
  node_orders["Order history<br/>[orders.tsx]"]
  node_wallet["Wallet screen<br/>[wallet.tsx]"]
  node_profile["Profile<br/>[profile.tsx]"]
  node_acquisition["Lead programme"]
  node_admin["Admin console<br/>[admin.tsx]"]
  node_ordercontext["Order state<br/>[OrderContext.tsx]"]
  node_walletcontext["Wallet state<br/>[WalletContext.tsx]"]
  node_authscreen["Login and onboarding<br/>[login.tsx]"]
end

subgraph group_services["App services"]
  node_orderservice["Order service<br/>[orderService.ts]"]
  node_socially["Number provider service<br/>[sociallyService.ts]"]
  node_payments["Paystack service<br/>[paystackService.ts]"]
  node_acqservice["Acquisition service"]
  node_settings["Settings service<br/>[settingsService.ts]"]
end

subgraph group_backend["Backend functions"]
  node_proxy["Number proxy<br/>[index.ts]"]
  node_purchase["Number purchase<br/>[index.ts]"]
  node_topup["Wallet top-up<br/>[index.ts]"]
  node_referral["Referral code<br/>[index.ts]"]
  node_paystackhook["Payment webhook<br/>[index.ts]"]
end

subgraph group_auth["Authentication"]
  node_authservice["Supabase auth<br/>[service.ts]"]
end

node_customer(("Customer"))
node_supabase[("Supabase")]
node_sociallysms["Socially SMS provider"]
node_paystack["Paystack"]

node_customer -->|"browses"| node_catalog
node_catalog -->|"loads catalog"| node_socially
node_socially -->|"invokes"| node_proxy
node_proxy -->|"proxies requests"| node_sociallysms
node_customer -->|"selects number"| node_checkout
node_checkout -->|"creates order"| node_orderservice
node_orderservice -->|"requests purchase"| node_purchase
node_purchase -->|"requests number"| node_sociallysms
node_purchase -->|"records order"| node_supabase
node_orders -->|"reads orders"| node_ordercontext
node_ordercontext -->|"loads orders"| node_orderservice
node_orderservice -->|"reads and updates"| node_supabase
node_customer -->|"opens wallet"| node_wallet
node_wallet -->|"uses state"| node_walletcontext
node_walletcontext -->|"reads wallet"| node_supabase
node_wallet -->|"starts top-up"| node_payments
node_payments -->|"requests top-up"| node_topup
node_topup -->|"initiates payment"| node_paystack
node_paystack -->|"sends events"| node_paystackhook
node_paystackhook -->|"updates records"| node_supabase
node_profile -->|"opens programme"| node_acquisition
node_acquisition -->|"loads programme"| node_acqservice
node_acqservice -->|"reads programme data"| node_supabase
node_acqservice -->|"submits code"| node_referral
node_admin -->|"manages programme"| node_acqservice
node_authscreen -->|"authenticates"| node_authservice
node_authservice -->|"uses auth"| node_supabase
node_catalog -->|"reads pricing setting"| node_settings
node_socially -->|"loads fee setting"| node_settings

click node_catalog "https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/index.tsx"
click node_checkout "https://github.com/supremeanalytics-limited/numvault/blob/main/app/checkout.tsx"
click node_orders "https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/orders.tsx"
click node_wallet "https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/wallet.tsx"
click node_profile "https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/profile.tsx"
click node_acquisition "https://github.com/supremeanalytics-limited/numvault/blob/main/app/acquisition-program.tsx"
click node_admin "https://github.com/supremeanalytics-limited/numvault/blob/main/app/admin.tsx"
click node_ordercontext "https://github.com/supremeanalytics-limited/numvault/blob/main/contexts/OrderContext.tsx"
click node_walletcontext "https://github.com/supremeanalytics-limited/numvault/blob/main/contexts/WalletContext.tsx"
click node_orderservice "https://github.com/supremeanalytics-limited/numvault/blob/main/services/orderService.ts"
click node_socially "https://github.com/supremeanalytics-limited/numvault/blob/main/services/sociallyService.ts"
click node_payments "https://github.com/supremeanalytics-limited/numvault/blob/main/services/paystackService.ts"
click node_acqservice "https://github.com/supremeanalytics-limited/numvault/blob/main/services/acquisitionService.ts"
click node_settings "https://github.com/supremeanalytics-limited/numvault/blob/main/services/settingsService.ts"
click node_authscreen "https://github.com/supremeanalytics-limited/numvault/blob/main/app/login.tsx"
click node_authservice "https://github.com/supremeanalytics-limited/numvault/blob/main/template/auth/supabase/service.ts"
click node_proxy "https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/socially-proxy/index.ts"
click node_purchase "https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/purchase-number/index.ts"
click node_topup "https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/wallet-topup/index.ts"
click node_referral "https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/apply-referral-code/index.ts"
click node_paystackhook "https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/paystack-webhook/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog,node_checkout,node_orders,node_wallet,node_profile,node_acquisition,node_admin,node_ordercontext,node_walletcontext,node_authscreen toneBlue
class node_orderservice,node_socially,node_payments,node_acqservice,node_settings,node_supabase toneAmber
class node_proxy,node_purchase,node_topup,node_referral,node_paystackhook toneMint
class node_authservice toneRose
class node_customer,node_sociallysms,node_paystack toneIndigo
```

## Components

### Mobile app

- [Number catalog](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/index.tsx): `app/(tabs)/index.tsx`
- [Checkout](https://github.com/supremeanalytics-limited/numvault/blob/main/app/checkout.tsx): `app/checkout.tsx`
- [Order history](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/orders.tsx): `app/(tabs)/orders.tsx`
- [Wallet screen](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/wallet.tsx): `app/(tabs)/wallet.tsx`
- [Profile](https://github.com/supremeanalytics-limited/numvault/blob/main/app/(tabs)/profile.tsx): `app/(tabs)/profile.tsx`
- [Lead programme](https://github.com/supremeanalytics-limited/numvault/blob/main/app/acquisition-program.tsx): `app/acquisition-program.tsx`
- [Admin console](https://github.com/supremeanalytics-limited/numvault/blob/main/app/admin.tsx): `app/admin.tsx`
- [Order state](https://github.com/supremeanalytics-limited/numvault/blob/main/contexts/OrderContext.tsx): `contexts/OrderContext.tsx`
- [Wallet state](https://github.com/supremeanalytics-limited/numvault/blob/main/contexts/WalletContext.tsx): `contexts/WalletContext.tsx`
- [Login and onboarding](https://github.com/supremeanalytics-limited/numvault/blob/main/app/login.tsx): `app/login.tsx`

### App services

- [Order service](https://github.com/supremeanalytics-limited/numvault/blob/main/services/orderService.ts): `services/orderService.ts`
- [Number provider service](https://github.com/supremeanalytics-limited/numvault/blob/main/services/sociallyService.ts): `services/sociallyService.ts`
- [Paystack service](https://github.com/supremeanalytics-limited/numvault/blob/main/services/paystackService.ts): `services/paystackService.ts`
- [Acquisition service](https://github.com/supremeanalytics-limited/numvault/blob/main/services/acquisitionService.ts): `services/acquisitionService.ts`
- [Settings service](https://github.com/supremeanalytics-limited/numvault/blob/main/services/settingsService.ts): `services/settingsService.ts`

### Backend functions

- [Number proxy](https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/socially-proxy/index.ts): `supabase/functions/socially-proxy/index.ts`
- [Number purchase](https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/purchase-number/index.ts): `supabase/functions/purchase-number/index.ts`
- [Wallet top-up](https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/wallet-topup/index.ts): `supabase/functions/wallet-topup/index.ts`
- [Referral code](https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/apply-referral-code/index.ts): `supabase/functions/apply-referral-code/index.ts`
- [Payment webhook](https://github.com/supremeanalytics-limited/numvault/blob/main/supabase/functions/paystack-webhook/index.ts): `supabase/functions/paystack-webhook/index.ts`

### Authentication

- [Supabase auth](https://github.com/supremeanalytics-limited/numvault/blob/main/template/auth/supabase/service.ts): `template/auth/supabase/service.ts`

### Other components

- **Customer**
- **Supabase**
- **Socially SMS provider**
- **Paystack**

## Connections

- Customer → Number catalog: browses
- Number catalog → Number provider service: loads catalog
- Number provider service → Number proxy: invokes
- Number proxy → Socially SMS provider: proxies requests
- Customer → Checkout: selects number
- Checkout → Order service: creates order
- Order service → Number purchase: requests purchase
- Number purchase → Socially SMS provider: requests number
- Number purchase → Supabase: records order
- Order history → Order state: reads orders
- Order state → Order service: loads orders
- Order service → Supabase: reads and updates
- Customer → Wallet screen: opens wallet
- Wallet screen → Wallet state: uses state
- Wallet state → Supabase: reads wallet
- Wallet screen → Paystack service: starts top-up
- Paystack service → Wallet top-up: requests top-up
- Wallet top-up → Paystack: initiates payment
- Paystack → Payment webhook: sends events
- Payment webhook → Supabase: updates records
- Profile → Lead programme: opens programme
- Lead programme → Acquisition service: loads programme
- Acquisition service → Supabase: reads programme data
- Acquisition service → Referral code: submits code
- Admin console → Acquisition service: manages programme
- Login and onboarding → Supabase auth: authenticates
- Supabase auth → Supabase: uses auth
- Number catalog → Settings service: reads pricing setting
- Number provider service → Settings service: loads fee setting