> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Client Architecture

> Architecture, screen navigation, AI Mentor integration, and Web3 wallet UX for the LearnWay mobile client (learnway-mobile/).

# Mobile Client Architecture (`learnway-mobile/`)

The LearnWay mobile application (`learnway-mobile/`) serves as the primary touchpoint for learners, combining gamified course delivery, real-time multiplayer quiz battles, an intelligent conversational AI Mentor, and an embedded Web3 smart account wallet.

***

## Core Application Modules

```
learnway-mobile/
├── lib/ (or src/)
│   ├── features/
│   │   ├── auth/            # Social login (Apple/Google), OTP flows, Session management
│   │   ├── courses/         # Course catalog, interactive slide viewer, quizzes
│   │   ├── ai_mentor/       # Conversational AI tab, voice input, contextual prompts
│   │   ├── battles/         # Live 1v1 PvP quiz battles, matchmaking, socket lifecycle
│   │   ├── wallet/          # Embedded smart wallet, token balances, transaction history
│   │   ├── gamification/    # Streaks, daily quest cards, XP/Gem animations, NFT badges
│   │   ├── payments/        # RevenueCat IAP paywalls, Fonbnk fiat on-ramp / off-ramp
│   │   └── notifications/   # FCM push receiver, in-app notification center
│   ├── core/
│   │   ├── network/         # Dio / Axios HTTP client with auto-refresh interceptors
│   │   ├── sockets/         # Socket.IO client manager with auto-reconnect
│   │   ├── storage/         # Secure storage (Keychain / EncryptedSharedPreferences)
│   │   └── theme/           # Design system tokens, dark/light mode, animations
```

***

## Key Mobile Features & User Journeys

### 1. The AI Mentor Tab

* **Persistent Companion**: Available from the main navigation bar. Learners can ask questions about active courses or general Web3 concepts.
* **Context Awareness**: The client attaches the current `courseId`, `lessonId`, and user skill level to prompt requests.
* **Streaming Responses & Voice**: Supports text chat and speech-to-text prompt submission with smooth rendering.

### 2. Interactive Slide & Quiz Engine

* **Micro-Learning Slides**: Renders rich media slides (text, syntax-highlighted code blocks, diagrams, video clips).
* **Instant Feedback**: Multiple-choice, drag-and-drop, and code-completion quizzes provide real-time explanations.
* **Optimistic Updates**: Progress and streak counters update locally before syncing to the backend.

### 3. Real-Time 1v1 Quiz Battles (WebSockets)

* **Matchmaking Screen**: Joins `/quiz-battles` namespace, displaying an animated 30-second matchmaking radar.
* **Turn-Based Battle View**: Synchronized countdown timers (15s per question), real-time opponent score animations, and final gem wager settlement.
* **Bot Seamless Fallback**: If no human opponent is found in 30 seconds, automatically transitions to a bot battle.

### 4. Embedded Web3 Smart Wallet & MPC Key Security (`SecretSharingService`)

LearnWay implements a non-custodial, seedless wallet experience powered by **SLIP-39 Multi-Party Computation (MPC) Shamir Secret Sharing**:

```mermaid theme={null}
graph TD
    subgraph ClientGen["📱 Client-Side Key Generation (ai_mentor)"]
        Seed["Master Private Key / Seed"]
        SLIPTree["SLIP-39 (2-of-3 Threshold)"]
        Seed --> SLIPTree
        SLIPTree --> S1["Share 1: localShare"]
        SLIPTree --> S2["Share 2: backendShare1"]
        SLIPTree --> S3["Share 3: backendShare2"]
    end

    subgraph StorageLocations["🔐 Distributed Storage & Encryption"]
        LocalSecure["Local Device Secure Storage<br/>(iOS Keychain / Android Keystore)<br/>• Encrypted with User Passphrase"]
        Argon2Envelope1["Argon2id Encrypted Envelope 1<br/>• Stored on Server DB"]
        Argon2Envelope2["Argon2id Encrypted Envelope 2<br/>• Stored on Server DB"]
    end

    S1 --> LocalSecure
    S2 -->|AES-GCM + Argon2id| Argon2Envelope1
    S3 -->|AES-GCM + Argon2id| Argon2Envelope2

    subgraph Recovery["🔄 Wallet Reconstruction (Threshold: 2 of 3)"]
        Reconstruct["Slip39.recoverSecret([Share A, Share B])<br/>• Rebuilds Master Key In-Memory Only<br/>• Server never holds plaintext shares"]
    end

    LocalSecure -.->|Normal Login| Reconstruct
    Argon2Envelope1 -.->|Decrypt via User Passphrase| Reconstruct
    Argon2Envelope2 -.->|Device Recovery Flow| Reconstruct
```

* **2-of-3 Threshold SLIP-39 Architecture**:
  * The master private key is generated client-side and split into **3 cryptographic SLIP-39 mnemonic shares**.
  * Any **2 of the 3 shares** can recover the master key. A single share reveals zero cryptographic information about the underlying secret.
* **Distribution of the 3 Shares**:
  1. **Share 1 (`localShare`)**: Stored on the learner's physical device inside hardware-backed secure storage (`FlutterSecureStorage` using `iOS Keychain` and `Android EncryptedSharedPreferences`), encrypted with the user's secret passphrase.
  2. **Share 2 (`backendShare1`)**: Encrypted client-side using **Argon2id key derivation + AES-GCM** with the user's passphrase/wallet context before being transmitted to the backend database.
  3. **Share 3 (`backendShare2` / Cloud Backup)**: Encrypted as a second independent Argon2id envelope and stored remotely on the backend server.
* **Zero-Knowledge Security Guarantee**:
  * The server holds two encrypted envelopes (`backendShare1` and `backendShare2`), but **neither can be decrypted without the user's client-side passphrase**. The backend has zero knowledge of the master key.
* **Seedless Multi-Device & Account Recovery**:
  * **Standard Session**: Mobile client unlocks `localShare` + decrypts `backendShare1` via PIN/passphrase to sign transactions.
  * **Lost/New Device**: The learner signs in via OAuth/OTP, downloads the two remote encrypted shares, inputs their personal passphrase to decrypt them, and restores their wallet instantly without manual 12-word seed phrases.
* **Gasless ERC-4337 Execution**:
  * Reconstructed keys sign UserOperations that are submitted to the hosted `/alto` bundler with gas sponsorship from the backend `VerifyingPaymaster`.

### 5. In-App Purchases & Subscriptions

* Integrates **RevenueCat** for cross-platform Apple App Store (StoreKit 2) and Google Play Billing.
* Automatically refreshes user entitlement state upon successful purchase or restore.