> For the complete documentation index, see [llms.txt](https://ribbit-wallet.gitbook.io/ribbit-wallet-whitepaper/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ribbit-wallet.gitbook.io/ribbit-wallet-whitepaper/technical-overview/system-architecture.md).

# System Architecture

**Mobile Application (Flutter Frontend)**

* **Cross-platform framework**: Single codebase for **iOS & Android** using **Flutter 3.x**.
* **State management**: **Riverpod + StateNotifier** for predictable state transitions.
* **Key security features**:
  * **Encrypted local storage** (using `flutter_secure_storage` with AES-256).
  * **Biometric authentication** (Face ID/Touch ID via biometric\_storage).
  * **Secure enclave usage** (where supported) for private key operations.
* **Transaction flow**:
  * **QR code scanning** for address input.
  * **Gas fee estimation** before signing.
  * **Real-time transaction tracking** via WebSocket.

#### **Wallet Core (Aptos SDK Integration)**

* **Key derivation**:
  * **BIP-39** mnemonic generation (12/24 words).
  * **BIP-44** deterministic wallet paths (`m/44'/637'/0'/0` for Aptos).
  * **Ed25519** key pairs for Aptos compatibility.
* **Transaction lifecycle**:
  * **Raw transaction construction** (Aptos ABI encoding).
  * **Client-side signing** (never exposes private keys).
  * **Submission via Supra Chain RPC**.

#### **Backend Services (Python + MongoDB)**

* **API layer**:
  * **FastAPI** for high-performance REST endpoints.
  * **JWT authentication** with short-lived tokens.
* **Database**:
  * **MongoDB** (sharded cluster for scalability).
  * **Stores**:
    * User preferences.
    * User wallet address and name.
    * Transaction metadata (not private keys).
    * Audit logs for compliance.
* **Security measures**:
  * **HSM-backed signing** for critical operations.
  * **IP filtering** and DDoS protection via Cloudflare.

**Blockchain Layer (Supra Chain + Move)**

* **Supra Chain advantages**:
  * **High TPS** (10,000+ transactions per second).
  * **Low latency** (sub-second finality).
  * **EVM compatibility** (future-proofing).
* **Move smart contracts**:
  * **Resource-oriented model** prevents double-spending.
  * **Module-based architecture** for reusable components.
  * **Formal verification** for security guarantees.