# zypp-labs/zypp-pay architecture

> Architecture diagram of the GitHub repository zypp-labs/zypp-pay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zypp-labs/zypp-pay
- Repository: https://github.com/zypp-labs/zypp-pay

## Overview

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: [`app/(tabs)/send.tsx`](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/send.tsx) (Send), [`app/(tabs)/receive.tsx`](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/receive.tsx) (Receive), [`app/(auth)/_layout.tsx`](https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/_layout.tsx) (Auth flow), [`app/(tabs)/_layout.tsx`](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/_layout.tsx) (Main tabs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_layout["App layout<br/>router shell<br/>[_layout.tsx]"]
  node_auth_layout["Auth flow<br/>router section<br/>[_layout.tsx]"]
  node_tabs_layout["Main tabs<br/>router section<br/>[_layout.tsx]"]
  node_welcome_screen["Welcome<br/>auth screen<br/>[welcome.tsx]"]
  node_create_account_screen["Create account<br/>auth screen<br/>[create-account.tsx]"]
  node_recover_account_screen["Recover account<br/>auth screen"]
  node_wallet_screen["Wallet<br/>[wallet.tsx]"]
  node_send_screen["Send<br/>payment screen<br/>[send.tsx]"]
  node_receive_screen["Receive<br/>payment screen<br/>[receive.tsx]"]
end

subgraph group_ui["Presentation"]
  node_ui_primitives["UI primitives<br/>design system<br/>[index.ts]"]
  node_ui_overlays["Overlays<br/>interaction UI"]
  node_error_boundary["Error boundary<br/>failure UI<br/>[ErrorBoundary.tsx]"]
end

subgraph group_domain["Domain logic"]
  node_transaction_engine["Transactions<br/>domain service<br/>[transaction.ts]"]
  node_intent_security["Intent security<br/>domain guard<br/>[intent-security.ts]"]
  node_sync_engine["Sync engine<br/>domain service<br/>[sync-engine.ts]"]
  node_account_service["Accounts<br/>domain service<br/>[user.ts]"]
end

subgraph group_data["Data layer"]
  node_local_db[("Local DB<br/>offline storage<br/>[schema.ts]")]
  node_typed_contracts["Contracts<br/>shared types<br/>[index.ts]"]
end

subgraph group_platform["Platform"]
  node_user_store["User store<br/>client state<br/>[useUserStore.ts]"]
  node_runtime_hooks["Runtime hooks<br/>device/runtime"]
  node_supabase_adapter["Supabase<br/>cloud adapter<br/>[supabase.ts]"]
  node_native_assets["Native assets<br/>asset bundle<br/>[ping-for-scan.mp3]"]
end

node_app_layout -->|"routes"| node_auth_layout
node_app_layout -->|"routes"| node_tabs_layout
node_auth_layout -->|"shows"| node_welcome_screen
node_auth_layout -->|"shows"| node_create_account_screen
node_auth_layout -->|"shows"| node_recover_account_screen
node_tabs_layout -->|"tab"| node_wallet_screen
node_tabs_layout -->|"tab"| node_send_screen
node_tabs_layout -->|"tab"| node_receive_screen
node_wallet_screen -->|"reads"| node_transaction_engine
node_send_screen -->|"creates"| node_transaction_engine
node_send_screen -->|"validates"| node_intent_security
node_receive_screen -->|"verifies"| node_intent_security
node_transaction_engine -->|"persists"| node_local_db
node_account_service -->|"persists"| node_local_db
node_sync_engine -->|"replays"| node_local_db
node_sync_engine -->|"syncs"| node_supabase_adapter
node_user_store -->|"feeds"| node_account_service
node_runtime_hooks -->|"signals"| node_user_store
node_runtime_hooks -->|"triggers"| node_sync_engine
node_wallet_screen -->|"uses"| node_ui_primitives
node_send_screen -->|"uses"| node_ui_overlays
node_receive_screen -->|"uses"| node_ui_primitives
node_error_boundary -->|"wraps"| node_wallet_screen
node_error_boundary -->|"wraps"| node_send_screen
node_error_boundary -->|"wraps"| node_receive_screen
node_typed_contracts -->|"types"| node_local_db
node_typed_contracts -->|"types"| node_transaction_engine
node_typed_contracts -->|"types"| node_account_service
node_native_assets -->|"supports"| node_receive_screen
node_native_assets -->|"supports"| node_ui_overlays

click node_app_layout "https://github.com/zypp-labs/zypp-pay/blob/main/app/_layout.tsx"
click node_auth_layout "https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/_layout.tsx"
click node_tabs_layout "https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/_layout.tsx"
click node_welcome_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/welcome.tsx"
click node_create_account_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/create-account.tsx"
click node_recover_account_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/recover-account.tsx"
click node_wallet_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/wallet.tsx"
click node_send_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/send.tsx"
click node_receive_screen "https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/receive.tsx"
click node_ui_primitives "https://github.com/zypp-labs/zypp-pay/blob/main/components/ui/index.ts"
click node_ui_overlays "https://github.com/zypp-labs/zypp-pay/blob/main/components/ui/privacy-overlay.tsx"
click node_error_boundary "https://github.com/zypp-labs/zypp-pay/blob/main/components/error-boundary/ErrorBoundary.tsx"
click node_transaction_engine "https://github.com/zypp-labs/zypp-pay/blob/main/backend/transaction.ts"
click node_intent_security "https://github.com/zypp-labs/zypp-pay/blob/main/backend/intent-security.ts"
click node_sync_engine "https://github.com/zypp-labs/zypp-pay/blob/main/backend/sync-engine.ts"
click node_account_service "https://github.com/zypp-labs/zypp-pay/blob/main/backend/user.ts"
click node_local_db "https://github.com/zypp-labs/zypp-pay/blob/main/db/local/schema.ts"
click node_typed_contracts "https://github.com/zypp-labs/zypp-pay/blob/main/types/index.ts"
click node_user_store "https://github.com/zypp-labs/zypp-pay/blob/main/store/useUserStore.ts"
click node_runtime_hooks "https://github.com/zypp-labs/zypp-pay/blob/main/hooks/useNetworkConnection.ts"
click node_supabase_adapter "https://github.com/zypp-labs/zypp-pay/blob/main/utils/supabase.ts"
click node_native_assets "https://github.com/zypp-labs/zypp-pay/blob/main/assets/sounds/ping-for-scan.mp3"

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_app_layout,node_auth_layout,node_tabs_layout,node_welcome_screen,node_create_account_screen,node_recover_account_screen,node_wallet_screen,node_send_screen,node_receive_screen toneBlue
class node_ui_primitives,node_ui_overlays,node_error_boundary toneAmber
class node_transaction_engine,node_intent_security,node_sync_engine,node_account_service toneMint
class node_local_db,node_typed_contracts toneRose
class node_user_store,node_runtime_hooks,node_supabase_adapter,node_native_assets toneIndigo
```

## Components

### App shell

Expo Router navigation and screen entrypoints.

- [App layout](https://github.com/zypp-labs/zypp-pay/blob/main/app/_layout.tsx): router shell · Top-level Expo Router provider and app bootstrap. · `app/_layout.tsx`
- [Auth flow](https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/_layout.tsx): router section · Authentication and account recovery routes. · `app/(auth)/_layout.tsx`
- [Main tabs](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/_layout.tsx): router section · Primary wallet, send, and receive navigation. · `app/(tabs)/_layout.tsx`
- [Welcome](https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/welcome.tsx): auth screen · Entry screen for new and returning users. · `app/(auth)/welcome.tsx`
- [Create account](https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/create-account.tsx): auth screen · Onboarding flow for new wallet creation. · `app/(auth)/create-account.tsx`
- [Recover account](https://github.com/zypp-labs/zypp-pay/blob/main/app/(auth)/recover-account.tsx): auth screen · Account recovery and backup restore flow. · `app/(auth)/recover-account.tsx`
- [Wallet](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/wallet.tsx): wallet screen · Balance, history, and wallet state view. · `app/(tabs)/wallet.tsx`
- [Send](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/send.tsx): payment screen · Creates a payment intent and starts transfer. · `app/(tabs)/send.tsx`
- [Receive](https://github.com/zypp-labs/zypp-pay/blob/main/app/(tabs)/receive.tsx): payment screen · Displays or scans payment information for exchange. · `app/(tabs)/receive.tsx`

### Presentation

Shared mobile UI primitives and error handling.

- [UI primitives](https://github.com/zypp-labs/zypp-pay/blob/main/components/ui/index.ts): design system · Shared buttons, inputs, views, lists, and layout primitives. · `components/ui/index.ts`
- [Overlays](https://github.com/zypp-labs/zypp-pay/blob/main/components/ui/privacy-overlay.tsx): interaction UI · Dialogs, sheets, drawers, privacy overlays, and pin entry. · `components/ui/privacy-overlay.tsx`
- [Error boundary](https://github.com/zypp-labs/zypp-pay/blob/main/components/error-boundary/ErrorBoundary.tsx): failure UI · General and network-specific error presentation. · `components/error-boundary/ErrorBoundary.tsx`

### Domain logic

Wallet, payment, sync, and account rules.

- [Transactions](https://github.com/zypp-labs/zypp-pay/blob/main/backend/transaction.ts): domain service · Creates and manages payment transaction lifecycle. · `backend/transaction.ts`
- [Intent security](https://github.com/zypp-labs/zypp-pay/blob/main/backend/intent-security.ts): domain guard · Validates payment intent safety and misuse prevention. · `backend/intent-security.ts`
- [Sync engine](https://github.com/zypp-labs/zypp-pay/blob/main/backend/sync-engine.ts): domain service · Replays and relays local activity when connectivity returns. · `backend/sync-engine.ts`
- [Accounts](https://github.com/zypp-labs/zypp-pay/blob/main/backend/user.ts): domain service · User state, identity, and backup coordination. · `backend/user.ts`

### Data layer

Local persistence and typed contracts.

- [Local DB](https://github.com/zypp-labs/zypp-pay/blob/main/db/local/schema.ts): offline storage · On-device schema and migration boundary for offline-first state. · `db/local/schema.ts`
- [Contracts](https://github.com/zypp-labs/zypp-pay/blob/main/types/index.ts): shared types · Shared user, transaction, sync, QR, and database types. · `types/index.ts`

### Platform

Runtime hooks, assets, and external service adapters.

- [User store](https://github.com/zypp-labs/zypp-pay/blob/main/store/useUserStore.ts): client state · Global session and user state for the app. · `store/useUserStore.ts`
- [Runtime hooks](https://github.com/zypp-labs/zypp-pay/blob/main/hooks/useNetworkConnection.ts): device/runtime · Connectivity, backup, and theme signals that affect behavior. · `hooks/useNetworkConnection.ts`
- [Supabase](https://github.com/zypp-labs/zypp-pay/blob/main/utils/supabase.ts): cloud adapter · Cloud integration point used by sync and account flows. · `utils/supabase.ts`
- [Native assets](https://github.com/zypp-labs/zypp-pay/blob/main/assets/sounds/ping-for-scan.mp3): asset bundle · Fonts, icons, and sounds for mobile-native feedback. · `assets/sounds/ping-for-scan.mp3`

## Connections

- 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.
