Technical Whitepaper
How to actually build WealthOS Wallet
The system architecture, technology stack, and multi-cloud deployment model behind the product, written for an engineering audience evaluating build, partner, or acquire.
Partner with usSystem Architecture
Six layers, each replaceable on its own
No layer assumes a specific cloud provider or a specific regulated partner. Each one talks to the layer next to it through a defined interface, so a partner, a provider, or a service inside the stack can change without the rest of the system noticing.
Mobile app (iOS & Android)
A React Native codebase sharing business logic across platforms, with native modules for NFC host-card emulation and Apple Pay / Google Pay tokenization.
API gateway
A single authenticated entry point for the app: request routing, rate limiting, and mTLS termination in front of every backend service.
WealthOS Connect (backend)
Event-driven microservices handling accounts, ledger, FX, and spend routing, each owning its own data store and talking to the others over an event bus, not direct calls.
Partner adapters
A dedicated adapter service per regulated partner: the Pakistani EMI's ledger API, the Saudi PSP's e-money and card-issuance API, the card network's tokenization service, and the cash-out network's code API.
Ledger & data layer
A double-entry ledger as the source of truth, event-sourced so every balance is a replayable sum of immutable entries, not a mutable counter.
Security & compliance layer
Tokenization, KYC/AML screening, and audit logging wrap every layer above, not bolted on afterward.
The Technology Stack
What actually runs in each layer
Mobile
- ●React Native (iOS & Android) with native NFC/HCE and Apple Pay / Google Pay modules
- ●Biometric login (Face ID / fingerprint) backed by the device secure enclave
- ●Offline-tolerant balance cache with optimistic UI, reconciled on reconnect
Backend services
- ●TypeScript/Node.js or Go microservices, one per domain: accounts, ledger, FX, cards, cash-out
- ●gRPC between internal services, REST/JSON at the API gateway
- ●An event bus (Kafka or a managed equivalent) for balance updates, screening results, and partner webhooks
Data & storage
- ●PostgreSQL for the transactional ledger, one schema per domain service
- ●Redis for session state and idempotency keys
- ●Object storage for KYC documents and evidence, encrypted at rest with per-object keys
Security
- ●Tokenized card data end to end, so PANs never touch WealthOS infrastructure in the clear
- ●mTLS between every internal service, OAuth2/OIDC for the app and partner APIs
- ●Secrets and encryption keys managed through Vault, backed by each cloud's native KMS/HSM
Platform
- ●Kubernetes (EKS/AKS/GKE/OKE) as the common runtime across providers
- ●Terraform modules per provider, one interface, four implementations
- ●GitOps deployment (Argo CD) with the same manifests promoted through every environment
Observability
- ●OpenTelemetry tracing across every service and partner call
- ●Centralized logs and metrics on a portable stack, not a provider-locked dashboard
- ●Automated alerting on ledger drift, screening latency, and partner API error rates
Multi-Cloud, On Purpose
No single cloud provider owns this architecture
Regulated payment data in Saudi Arabia generally needs to sit in-Kingdom, and today that has one mature answer, Oracle's existing Jeddah region, with AWS, Azure, and Google Cloud each having announced a Saudi region of their own. Building against one provider's proprietary services would mean re-architecting the moment the regulatory or commercial picture changes. Building cloud-agnostic from the start means that choice stays open.
| Provider | Regional presence | Relevant services | Role in this architecture |
|---|---|---|---|
| Oracle Cloud (OCI) | A live region in Jeddah, Saudi Arabia today; a Riyadh region announced | OKE, Autonomous Database, Vault, S3-compatible Object Storage | Default choice for anything that must sit in-Kingdom right now, given the already-live Jeddah region. |
| Amazon Web Services | Middle East (UAE) region live; a Saudi Arabia region announced | EKS, RDS/Aurora, KMS, CloudHSM, MSK | Candidate primary for shared/global services today, moving in-Kingdom workloads over once its Saudi region is live. |
| Microsoft Azure | UAE regions live; a Saudi Arabia region announced with local partner stc | AKS, Azure Database for PostgreSQL, Key Vault, Managed HSM, Event Hubs | Strong fit where a partner institution already standardizes on Microsoft, and for its sovereignty tooling. |
| Google Cloud | A Qatar region live; a Saudi Arabia region announced with stc Group | GKE, Cloud SQL, Cloud KMS, Pub/Sub | A fit for analytics and fraud-scoring workloads run alongside a second provider for core services. |
Regional presence and roadmap details are illustrative and change as each provider expands, always confirm current availability directly with the provider before committing to a region.
Where Each Workload Actually Runs
Regional deployment map
| Workload | Primary location | Why |
|---|---|---|
| SAR ledger, card issuance, cash-out network | In-Kingdom: Oracle OCI Jeddah today, with AWS, Azure, and GCP Saudi regions added as each goes live | SAMA's cloud and data-residency rules for regulated payment data |
| KYC and the PKR ledger | Hosted on the Pakistani EMI or Exchange Company's own compliant infrastructure | SBP requires this data to stay within the licensed partner’s own environment; WealthOS connects over API only |
| Mobile backend, non-PII orchestration, WealthOS Connect gateway | Multi-region across two providers (for example AWS UAE plus a second provider) | Latency to both markets, and resilience if one provider has a regional incident |
| Analytics, fraud scoring, FX modeling | Whichever provider's managed analytics stack fits the workload best | Not regulated customer data, so free to run wherever it is fastest or cheapest |
How It Stays Portable
Four rules that keep a provider swap a config change, not a rewrite
Every service ships as a container and runs on EKS, AKS, GKE, or OKE identically. The orchestration layer, not the provider, is the abstraction.
One module interface, four implementations. Standing up a workload on a new provider means writing a module against the same interface, not redesigning the workload.
PostgreSQL instead of a provider-specific database engine, S3-compatible object storage everywhere, so a managed equivalent on any provider is a drop-in.
Secrets and application-level encryption keys are requested from Vault, which in turn is backed by whichever provider's native KMS or HSM sits underneath it that day.
Security & Compliance Architecture
Built to the standard the regulators already require
Card data
Tokenized end to end. Raw PANs live in the card network’s vault, never in WealthOS infrastructure, which keeps PCI DSS scope to a minimum.
Encryption
AES-256 at rest and TLS 1.3 in transit everywhere, with keys custodied by each provider’s KMS or a dedicated HSM.
Network
Zero-trust internally: mTLS between every service, no implicit trust from being inside the network perimeter.
Audit trail
Every ledger entry and every screening decision is immutable and replayable, so an audit never depends on a log that could have been edited.
The program aligns to ISO 27001 for the WealthOS technology layer, SAMA's Cyber Security Framework for the Saudi leg of the stack, and the State Bank of Pakistan's technology governance and risk requirements for the Pakistan leg, each enforced by the regulated partner responsible for that side of the corridor.
Integration Patterns
Three regulated partners means three different failure modes
Every partner integration assumes the partner's API will be slow, briefly unavailable, or occasionally inconsistent, because it eventually will be.
- ●Idempotency keys on every mutating call (funding, spend, cash-out), so a retried request never double-processes
- ●Circuit breakers and exponential backoff around every partner integration
- ●Webhook events with a polling fallback, since not every partner exposes real-time webhooks
- ●gRPC internally for typed, low-latency service-to-service calls; REST/JSON at the public and partner-facing edges
Disaster Recovery
A second provider, not just a second region
A regional outage at a single provider is a bigger risk than most disaster-recovery plans account for. The ledger's event log is replicated nightly to a second provider's object storage, not just a second region of the same one, and failover between them is rehearsed on a schedule, not discovered during an actual incident. The target is an RTO under 15 minutes and an RPO close to zero for the ledger, since event sourcing means the balance is always a replayable sum, never a single row that can be silently lost.
Implementation Roadmap
Three phases, from one region to active-active
MVP
One in-Kingdom region (Oracle OCI Jeddah) plus one shared-services provider, one corridor (Pakistan to KSA), the core app, card issuance, and NFC payments, with cash-out reconciliation still partly manual.
Harden
Multi-region within the primary provider, fully automated reconciliation, the complete observability stack, and a second cloud provider added for shared-services redundancy.
Scale
Active-active multi-cloud for in-Kingdom workloads as AWS, Azure, and GCP Saudi regions come online, additional corridors beyond Pakistan, and ML-based fraud scoring in production.
Partner With Us
Evaluating build, partner, or acquire?
This document covers the architecture at a level meant for an engineering or infrastructure conversation. Book a call to go deeper on any layer, the partner integrations, or the cloud rollout sequencing.
Partner with us