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

# System Architecture & Ecosystem Topology

> Full-system architecture map covering mobile client, core backend API, smart contracts, Alto ERC-4337 bundler, and transaction relayer.

# System Architecture & Ecosystem Topology

LearnWay operates a clear dual on-chain model:

1. **Backend Smart Contract Execution**: The core backend (`learnway-backend`) drives platform state changes (XP, Gems, Badges, Certificates) through the **LearnWay Manager** smart contract, using `learnway-transaction-processor` as the dedicated transaction relayer.
2. **Client-Side ERC-4337 Account Abstraction**: The mobile app (`learnway-mobile/`) uses smart accounts for user-initiated transactions. It gets gas sponsorship from the backend's `VerifyingPaymaster` and dispatches `UserOperation`s directly to the self-hosted **Alto Bundler** (`/alto`).

```mermaid theme={null}
graph TD
    subgraph Clients["📱 Client Layer (Mobile App)"]
        Mobile["Mobile App (ai_mentor)"]
    end

    subgraph CoreBackend["⚡ Core Backend (learnway-backend)"]
        Backend["LearnWay Core Monolith"]
    end

    subgraph RelayerAndBundler["⚙️ Execution & Indexing Layer"]
        TxProcessor["Transaction Processor (Relayer)"]
        Alto["Alto Bundler (/alto)"]
        TxAPI["Goldsky Indexer API (transactions_apiv2)"]
    end

    subgraph OnChain["⛓️ Lisk L2 Blockchain"]
        EntryPoint["ERC-4337 EntryPoint 0.7"]
        LearnWayManager["LearnWay Manager Contract"]
        XPContract["XPContract (Gamification & Levels)"]
        GemContract["GemContract (Gems Ledger & Rewards)"]
        BadgesContract["LearnWayBadges NFT (ERC-721)"]
        CertsContract["LearnWayCertificates (ERC-1155)"]
        LiskNodes["Lisk L2 RPC Node"]
    end

    %% Backend Execution Path
    Mobile -->|REST API v2 / Complete Lesson| Backend
    Backend -->|Dispatch On-Chain Actions| TxProcessor
    TxProcessor -->|Relay & Execute Tx| LearnWayManager
    LearnWayManager --> XPContract
    LearnWayManager --> GemContract
    LearnWayManager --> BadgesContract
    LearnWayManager --> CertsContract

    %% Frontend ERC-4337 Path (Mobile Only)
    Mobile -->|1. Request Gas Sponsorship| Backend
    Backend -->|2. Signed paymasterAndData| Mobile
    Mobile -->|3. eth_sendUserOperation| Alto
    Alto -->|4. Bundle & Execute handleOps| EntryPoint
    EntryPoint -->|5. Gasless Execution| TargetTokens["Target Contracts (USDT / Smart Account)"]

    %% Indexing Path
    TxAPI -->|Index Blocks & Events| LiskNodes
    Mobile -->|Fetch Wallet Ledger History| TxAPI
```

***

## Dual On-Chain Execution Model

### 1. Backend Relayer Pipeline (`learnway-transaction-processor`)

* **Scope**: All automated and platform-driven smart contract interactions.
* **Flow**:
  * Learner completes a lesson, quiz, battle, or course on the mobile app.
  * `learnway-backend` verifies completion and calls internal contract services (`LearnWayManagerService`, `XpContractService`, `GemContractService`, `BadgesNftService`, `CertificateNftService`).
  * `learnway-transaction-processor` acts as the relayer: manages server wallet nonces, estimates gas, submits transactions to the **LearnWay Manager** contract on Lisk L2, and monitors block confirmations.

### 2. Frontend ERC-4337 Account Abstraction (`ai_mentor/` + `/alto`)

* **Scope**: Exclusively used on the client (mobile) side for user-initiated smart account transactions.
* **Flow**:
  * Mobile client creates a `UserOperation`.
  * Mobile client requests sponsorship from `POST /paymaster/rpc/:chainId` (`VerifyingPaymaster`).
  * Backend signs `paymasterAndData` if the request meets policy/whitelist checks.
  * Mobile client sends the signed `UserOp` to the self-hosted **Alto Bundler** (`/alto`).
  * Alto bundles and executes the operation via the ERC-4337 `EntryPoint` contract on Lisk L2.

***

## Ecosystem Subsystem Summary

| Subsystem                              | Primary Role                              | On-Chain Interaction Type                                                                                                                   |
| :------------------------------------- | :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| **`learnway-mobile/`**                 | Mobile Application                        | **ERC-4337 Account Abstraction** (sends UserOps to `/alto`)                                                                                 |
| **`learnway-backend`**                 | Core Business API & Manager Orchestration | Initiates relayer jobs for **LearnWay Manager**; signs Paymaster data                                                                       |
| **`/alto`**                            | Hosted ERC-4337 Bundler                   | Bundles mobile client UserOps and executes them via `EntryPoint`                                                                            |
| **`learnway-transaction-processor/`**  | Blockchain Transaction Relayer            | Relays and submits backend transactions to Lisk L2 contracts                                                                                |
| **`learnway_onchain_infrastructure/`** | Smart Contracts on Lisk L2                | `LearnWayAdmin` (RBAC), `LearnWayManager` (Coordinator), `GemsContract`, `XPContract`, `BadgesNFT`, `CertificatesNFT`, `VerifyingPaymaster` |
| **`transactions_apiv2/`**              | Goldsky Event Indexer API                 | Indexes all contract events into fast wallet history query endpoints                                                                        |
| **`learnway-ai-service/`**             | Standalone AI Engine                      | Google Gemini tutoring, assessments, and capstone code evaluations                                                                          |
| **`learnway-notification-service/`**   | Notification Microservice                 | FCM push notifications and Resend transactional emails                                                                                      |