Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
175 lines (154 loc) · 5.75 KB

ARCHITECTURE.md

File metadata and controls

175 lines (154 loc) · 5.75 KB

ProofLearn Architecture

System Overview

graph TB
    subgraph "World App"
        UI[ProofLearn Mini App]
        IDKit["IDKit 4.0 Widget"]
        MK["MiniKit 2.0"]
    end

    subgraph "Next.js Server"
        RP["/api/rp-signature"]
        VER["/api/verify → v4 API"]
        TUTOR["/api/tutor/*"]
        AUTH["Session (JWT)"]
        RL["Rate Limiter"]
    end

    subgraph "External Services"
        WID["World ID v4 Cloud API"]
        CLAUDE["Claude API"]
    end

    subgraph "Data Layer"
        PRISMA[Prisma ORM]
        DB[(SQLite / PostgreSQL)]
    end

    UI -->|"signRequest()"| RP
    IDKit -->|"proof payload"| VER
    MK -->|"walletAuth, haptics, share"| UI

    VER -->|"POST /api/v4/verify/{rp_id}"| WID
    TUTOR -->|"generate/evaluate/chat"| CLAUDE

    RP --> AUTH
    VER --> AUTH
    TUTOR --> AUTH
    TUTOR --> RL

    VER --> PRISMA
    TUTOR --> PRISMA
    PRISMA --> DB
Loading

World ID 4.0 Flow

sequenceDiagram
    participant L as Learner
    participant FE as ProofLearn Frontend
    participant RP as /api/rp-signature
    participant VER as /api/verify
    participant WID as developer.world.org/api/v4

    L->>FE: Tap "Verify with World ID"
    FE->>RP: POST {action: "verify-learner"}
    Note over RP: signRequest(action, signingKey)<br/>from @worldcoin/idkit/signing
    RP-->>FE: {sig, nonce, created_at, expires_at}
    FE->>FE: Open IDKitRequestWidget<br/>preset: orbLegacy()
    Note over FE: IDKit handles proof generation<br/>inside World App (native) or<br/>via QR code (browser)
    FE-->>FE: handleVerify callback with proof
    FE->>VER: POST {rp_id, idkitResponse}
    VER->>WID: POST /api/v4/verify/{rp_id}<br/>body: idkitResponse (AS-IS)
    WID-->>VER: {success, nullifier, ...}
    Note over VER: findOrCreateLearner(nullifier)
    VER-->>FE: {success, learnerId} + session cookie
    FE-->>L: Redirect to /setup
Loading

MiniKit 2.0 Integration Points

Feature Where Used SDK Call
Provider providers.tsx <MiniKitProvider> wraps entire app
Detection providers.tsx MiniKit.isInstalled()
WalletAuth lib/minikit.ts MiniKit.walletAuth({nonce, statement})
Haptics lib/minikit.ts → learn page MiniKit.sendHapticFeedback({hapticsType, style})
Share lib/minikit.ts → settings navigator.share() (works in World App webview)

Data Model

erDiagram
    Learner {
        string id PK
        string nullifierHash UK "World ID v4 nullifier"
        string walletAddress "From MiniKit walletAuth"
        string displayName
        string preferredSubject
        string skillLevel
        string preferredLanguage "en, fr, hu, uk, es"
        int totalLessons
        int totalCorrect
        int totalAnswered
        int currentStreak
        int longestStreak
        datetime lastActiveAt
    }

    LearnerSession {
        string id PK
        string learnerId FK
        string token UK "JWT"
        datetime expiresAt
    }

    Lesson {
        string id PK
        string learnerId FK
        string subject
        string level
        string topic
        string content
        string question
        string questionType
        string options "JSON array"
        string hint
        string userAnswer
        boolean isCorrect
        int score "0-100"
        string feedback
        int difficulty "1-5"
        datetime completedAt
    }

    Learner ||--o{ LearnerSession : has
    Learner ||--o{ Lesson : completes
Loading

File Structure

src/
├── app/
│   ├── layout.tsx              # Root layout with MiniKitProvider
│   ├── providers.tsx           # MiniKitProvider + AppStateProvider
│   ├── page.tsx                # Landing — IDKitRequestWidget
│   ├── setup/page.tsx          # Subject, language & level selection
│   ├── learn/page.tsx          # Tutor session + haptic feedback + mentor chat
│   ├── mentor/page.tsx         # General AI mentor chat
│   ├── progress/page.tsx       # Dashboard with stats
│   ├── settings/page.tsx       # Profile, share, reset
│   └── api/
│       ├── rp-signature/       # RP signature for IDKit 4.0
│       ├── verify/             # World ID v4 proof verification
│       ├── auth/nonce/         # SIWE nonce generation
│       ├── auth/wallet/        # MiniKit walletAuth verification
│       ├── learner/            # Learner CRUD
│       ├── tutor/lesson/       # AI lesson generation
│       ├── tutor/evaluate/     # AI answer evaluation
│       ├── tutor/chat/         # AI mentor chat
│       ├── progress/           # Progress stats
│       └── reset/              # Reset progress
├── components/
│   ├── Navigation.tsx          # Tab navigation (Learn, Mentor, Progress, Settings)
│   ├── MentorChat.tsx          # Reusable chat widget
│   └── Markdown.tsx            # Lightweight markdown renderer
├── lib/
│   ├── db.ts                   # Prisma client
│   ├── ai.ts                   # Claude API for lessons and evaluation
│   ├── session.ts              # JWT session management
│   ├── rate-limit.ts           # In-memory rate limiter
│   ├── verification.ts         # Learner creation from nullifier
│   └── minikit.ts              # MiniKit helpers (haptics, walletAuth, share)
├── types/
│   └── index.ts                # Shared types, subjects, languages
└── __tests__/
    ├── verification.test.ts    # Learner creation tests
    ├── tutor.test.ts           # AI tutor tests (mocked Anthropic)
    ├── rate-limit.test.ts      # Rate limiter tests
    └── worldid.test.ts         # IDKit signRequest tests