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

# Courses & Lessons System

> Hierarchical educational content structure: Learning Paths, Courses, Lessons, Interactive Slides, and Progression Tracking.

# Courses & Lessons System

The learning engine is designed around modular, micro-learning concepts. It breaks down complex knowledge into interactive lessons and slide-by-slide experiences with quizzes and practical checkpoints.

```mermaid theme={null}
graph TD
    LP[Learning Path] --> Course1[Course 1]
    LP --> Course2[Course 2]
    Course1 --> Lesson1[Lesson 1]
    Course1 --> Lesson2[Lesson 2]
    Lesson1 --> Slide1[Slide 1: Theory / Text]
    Lesson1 --> Slide2[Slide 2: Code Snippet / Media]
    Lesson1 --> Slide3[Slide 3: Interactive Quiz Question]
```

***

## Data Hierarchy

### 1. Learning Paths (`learning_paths`)

* Broad educational domains (e.g., *Web3 Development*, *Financial Literacy*, *AI Engineering*).
* Can be marked as `isPremium` or standard.

### 2. Courses (`courses`)

* Specific subject units with defined difficulty levels (`BEGINNER`, `INTERMEDIATE`, `ADVANCED`).
* Contains metadata: `estimatedCompletionMinutes`, `skillsGained`, `prerequisites`, `targetAudience`, and `certificateEligible`.
* Linked to on-chain course registry (`onChainCourseId`) for verifiable credentials.

### 3. Lessons (`lessons`)

* Discrete, 5-15 minute learning modules.
* Tracks `xpReward` and `gemReward` earned upon first completion.

### 4. Lesson Slides (`lesson_slides`)

* Slide types: `THEORY`, `CODE_EXAMPLE`, `QUESTION`, `RECAP`, `MEDIA`.
* Rich formatting with localized translations.

***

## User Progress & Reward Calculation

When a user interacts with learning material, progress is recorded across several relational tables:

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor User as Student
    participant API as Course Controller
    participant Service as UserLesson Service
    participant Reward as Reward Engine
    participant DB as PostgreSQL
    participant Bull as Bull Queue (Blockchain)

    User->>API: POST /api/v2/user-lesson/complete
    API->>Service: markLessonComplete(userId, lessonId)
    Service->>DB: Check if already completed
    alt First Time Completion
        Service->>DB: Save UserLesson (status=COMPLETED)
        Service->>Reward: calculateReward(xp, gems)
        Reward->>DB: Update User (totalXP, totalGems, streaks)
        Reward->>Bull: Enqueue on-chain reward transaction
    else Subsequent Completion
        Service->>DB: Update lastReviewedAt (no duplicate rewards)
    end
    Service-->>API: Return completion status & rewards summary
    API-->>User: 200 OK (XP earned, streak updated)
```

***

## Content Localization & Translation

All course and lesson endpoints pass through `TranslationInterceptor`. If the client supplies `Accept-Language` or has a configured `preferredLanguage`, texts are automatically translated and cached using Google Cloud Translate.