How zypp-labs/zypp-pay works
Zypp Pay is an Expo/React Native mobile app, not a traditional web app. The architecture is centered on an offline-first wallet/payment client that can create, validate, and exchange payment intents locally, then sync and settle them once connectivity returns.
1. App shell and navigation
The app/ directory uses an Expo Router-style structure. The top-level _layout.tsx likely wires global providers, while app/(auth) and app/(tabs) split the app into authentication flows and the main wallet experience. The main user journeys are welcome, create-account, recover-account, then the tabbed wallet, send, and receive screens.
2. Primary product flows
The core flows are payment-oriented rather than content-oriented:
- send: initiate a payment
- receive: present or scan payment information
- wallet: view balance/history/state
This matches the README’s offline QR-based payment model, where users exchange signed transaction data before network settlement.
3. Presentation layer
components/ui/ is a shared design system of low-level primitives and composed controls: buttons, inputs, dialogs, sheets, tables, privacy overlays, swipe-to-pay, pin entry, and permission requests. This layer isolates cross-platform UI differences and keeps screens thin. components/error-boundary/ handles failure states, including network-specific errors.
4. Client state and session management
store/useUserStore.ts is the main global client store for user/session state. Supporting hooks such as useNetworkConnection, useGoogleBackup, useThemeColor, and useColorScheme provide runtime signals that affect UI and sync behavior. This suggests the app reacts to connectivity, theme, and backup availability at the edge.
5. Offline persistence boundary
db/local/schema.ts and db/migrations/ define the local data model and schema evolution for offline storage. The presence of types/database.ts indicates the app has a typed persistence layer, likely serving as the source of truth while offline. The local database is a critical boundary because transaction creation and verification must work without the cloud.
6. Domain logic lives under backend/
Although named backend, these modules are part of the mobile app’s domain/service layer:
- transaction.ts for transaction creation and lifecycle
- sync-engine.ts for replaying/relaying local activity when online
- intent-security.ts for validating payment intent safety and preventing misuse
- user.ts and backup.ts for account/user state and recovery/backup flows
This layer sits between screens and persistence, coordinating the offline-first business rules.
7. Sync and settlement path
The README describes a two-phase model: transactions are created and exchanged locally first, then propagated and settled later. That implies a data flow of:
UI action → local signed transaction/intent → local persistence → sync engine → external relay/cloud settlement.
utils/supabase.ts suggests there is also a cloud integration point, while the README notes the actual relayer/settlement infrastructure is proprietary and not open source.
8. Shared contracts and typed data
The types/ directory contains shared schemas for user, transaction, sync, qr, and database. These types are the contract between UI, storage, and sync logic, which is important for an offline system where mismatched state can create double-spend or reconciliation bugs.
9. QR and device-to-device exchange
The presence of types/qr.ts, send/receive screens, and the scan sound asset strongly indicates QR-based transaction exchange. This is the offline handshake boundary: one device creates a payment artifact, the other reads/verifies it, and both can proceed without internet.
10. Security and user trust boundaries
Security is designed to keep private keys on-device, with cryptographic signing happening locally. intent-security.ts and the privacy-related UI components show a split between visible UX confirmation and hidden enforcement logic. The app’s architecture likely treats “user intent” and “signed transaction” as separate stages to reduce fraud and accidental spending.
11. UX, feedback, and device integration
Assets such as fonts, icons, and sounds support a polished mobile-native experience. Haptics, permission requesters, and platform-specific UI files (*.ios.tsx) show that the app adapts to native device capabilities rather than using a single generic interface.
12. Tooling and runtime
The repo is configured for an Expo-managed React Native stack with Babel, Metro, EAS, Tailwind/NativeWind, and platform-specific component shims. This matters architecturally because it explains why the app can ship a single codebase across iOS/Android while still using native device behaviors and offline storage.
Overall, the key diagram boundary is: mobile UI and local state on one side; local offline persistence and transaction/security logic in the middle; external sync/relay services on the other side. The system is intentionally designed so payment creation and validation do not depend on live internet connectivity.
Main entry points: send.tsx Send · receive.tsx Receive · (auth)/_layout.tsx Auth flow · (tabs)/_layout.tsx Main tabs
Components 22
App shell
Expo Router navigation and screen entrypoints.
- App layout · Top-level Expo Router provider and app bootstrap.
app/_layout.tsx - Auth flow · Authentication and account recovery routes.
app/(auth)/_layout.tsx - Main tabs · Primary wallet, send, and receive navigation.
app/(tabs)/_layout.tsx - Welcome · Entry screen for new and returning users.
app/(auth)/welcome.tsx - Create account · Onboarding flow for new wallet creation.
app/(auth)/create-account.tsx - Recover account · Account recovery and backup restore flow.
app/(auth)/recover-account.tsx - Wallet · Balance, history, and wallet state view.
app/(tabs)/wallet.tsx - Send · Creates a payment intent and starts transfer.
app/(tabs)/send.tsx - Receive · Displays or scans payment information for exchange.
app/(tabs)/receive.tsx
Presentation
Shared mobile UI primitives and error handling.
- UI primitives · Shared buttons, inputs, views, lists, and layout primitives.
components/ui/index.ts - Overlays · Dialogs, sheets, drawers, privacy overlays, and pin entry.
components/ui/privacy-overlay.tsx - Error boundary · General and network-specific error presentation.
components/error-boundary/ErrorBoundary.tsx
Domain logic
Wallet, payment, sync, and account rules.
- Transactions · Creates and manages payment transaction lifecycle.
backend/transaction.ts - Intent security · Validates payment intent safety and misuse prevention.
backend/intent-security.ts - Sync engine · Replays and relays local activity when connectivity returns.
backend/sync-engine.ts - Accounts · User state, identity, and backup coordination.
backend/user.ts
Data layer
Local persistence and typed contracts.
Platform
Runtime hooks, assets, and external service adapters.
- User store · Global session and user state for the app.
store/useUserStore.ts - Runtime hooks · Connectivity, backup, and theme signals that affect behavior.
hooks/useNetworkConnection.ts - Supabase · Cloud integration point used by sync and account flows.
utils/supabase.ts - Native assets · Fonts, icons, and sounds for mobile-native feedback.
assets/sounds/ping-for-scan.mp3
Connections 30
- App layout → Auth flow: routes · Bootstraps authentication flow.
- App layout → Main tabs: routes · Bootstraps main app navigation.
- Auth flow → Welcome: shows · Landing entry for auth users.
- Auth flow → Create account: shows · Routes into account creation.
- Auth flow → Recover account: shows · Routes into account recovery.
- Main tabs → Wallet: tab · Main wallet overview.
- Main tabs → Send: tab · Payment initiation flow.
- Main tabs → Receive: tab · Payment receipt flow.
- Wallet → Transactions: reads · Renders transaction and balance state.
- Send → Transactions: creates · Builds local payment intents and transactions.
- Send → Intent security: validates · Checks intent safety before commit.
- Receive → Intent security: verifies · Confirms received payment artifacts.
- Transactions → Local DB: persists · Stores offline transaction state.
- Accounts → Local DB: persists · Stores account and recovery state.
- Sync engine → Local DB: replays · Consumes local activity for sync.
- Sync engine → Supabase: syncs · Uses cloud integration when online.
- User store → Accounts: feeds · Provides session and user context.
- Runtime hooks → User store: signals · Updates state based on connectivity and device context.
- Runtime hooks → Sync engine: triggers · Connectivity changes can start sync.
- Wallet → UI primitives: uses · Composes shared UI controls.
- Send → Overlays: uses · Uses secure interaction and confirmation surfaces.
- Receive → UI primitives: uses · Uses shared presentation controls.
- Error boundary → Wallet: wraps · Handles wallet view failures.
- Error boundary → Send: wraps · Handles send flow failures.
- Error boundary → Receive: wraps · Handles receive flow failures.
- Contracts → Local DB: types · Defines persistence schema contracts.
- Contracts → Transactions: types · Shares transaction and sync structures.
- Contracts → Accounts: types · Shares user and recovery structures.
- Native assets → Receive: supports · Scan and feedback assets reinforce QR exchange.
- Native assets → Overlays: supports · Supports mobile-native interaction polish.