Architecture | SplitPay Docs

SplitPay adheres to a strict separation of concerns: the blockchain contract is the financial authority, while web and mobile applications act as non-custodial presentation and transaction preparation clients.

System Architecture Diagram

                        Stellar Network (Testnet)
                                   │
                           SplitPay Contract
                       (Soroban WASM in Rust)
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
        splitpay-web        splitpay-mobile        splitpay-sdk
      (Next.js 16 dApp)     (React Native)      (TypeScript Client)
              │                    │                    │
              └────────────────────┼────────────────────┘
                                   │
                              splitpay-api
                      (Optional Indexing / Metadata)

Layer Responsibilities

1. SplitPay Contract (Soroban)

On-chain pool & member configuration storage
10,000 BPS validation enforcement
Atomic token pull & disbursement (SEP-41)
Deterministic integer remainder handling
Immutable historical distribution receipts
Structured event emission

2. Web Application (Next.js 16)

Freighter extension & Dev Keypair wallet integration
Simulation of contract calls via Horizon / Soroban RPC
XDR assembly, signing, and submission polling
Interactive pool creation with live BPS validation
Transaction status tracking and receipt presentation

3. Mobile Client (React Native)

Mobile-optimized pool explorer and balance inspector
Deep-link wallet signing (WalletConnect / Albedo)
Shared business rules via common SDK library

4. API & Indexer (Optional Infrastructure)

Off-chain metadata (display names, avatars, memos)
Ingestion and indexing of contract events
Webhook dispatching for payment settlements
Fast cached queries without direct ledger reads

On-Chain vs Off-Chain Boundary

To maintain high performance and low storage footprints on Stellar, only essential financial and authorization state is stored on-chain:

On-Chain (Soroban Contract)	Off-Chain (Client / API)
Pool ID, Owner Address, Asset Address	Pool name, description, category tags
Member Addresses & Basis Points (BPS)	Member avatars, nicknames, email notifications
Payment ID, Gross Amount, Settlement Status	Invoice PDFs, project milestone descriptions
Historical Distributions (Recipient, Amount, BPS)	Analytics charts, aggregated accounting exports

End-to-End Data Flow

When an action (such as creating a pool or settling a payment) is performed from splitpay-web:

Form Validation: Web client validates address formatting and ensures total shares equal 10,000 BPS.
Transaction Assembly: Client calls prepareInvocationTx() using the Stellar SDK.
RPC Simulation: The transaction is sent to https://soroban-testnet.stellar.org via simulateTransaction to estimate footprints and fees.
Wallet Signing: Assembled transaction XDR is signed by the user's Freighter wallet or local dev keypair.
Broadcast & Polling: Signed XDR is broadcast to the network; the web app polls getTransaction until status is SUCCESS.