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

# Gamification & Competitions

> Gamification engine: Experience Points (XP), Gems, Streaks, Badges, Leaderboards, Contests, and Quiz Battles.

# Gamification & Competitions

LearnWay treats engagement and motivation as first-class architectural components. Gamification elements are deeply integrated into daily learning habits and competitive events.

***

## The Reward Hierarchy

```
┌───────────────────────────────────────────────────────────┐
│                    LEARNING ACTIVITY                      │
│      (Lessons, Daily Quizzes, Quiz Battles, Contests)      │
└─────────────────────────────┬─────────────────────────────┘
                              │
               ┌──────────────┴──────────────┐
               ▼                             ▼
       ┌───────────────┐             ┌───────────────┐
       │   XP Points   │             │  Gems Points  │
       │ (Reputation & │             │(In-App Utility│
       │  Leaderboard) │             │& Battle Stake)│
       └───────┬───────┘             └───────┬───────┘
               │                             │
               ▼                             ▼
       ┌───────────────┐             ┌───────────────┐
       │  Leaderboard  │             │ PvP Battles,  │
       │   Rankings    │             │Streak Freezes,│
       │ (Weekly/Month)│             │Contest Entries│
       └───────────────┘             └───────────────┘
```

***

## 1. XP & Gems

* **Experience Points (XP)**: Non-transferable computational metric measuring effort, streak discipline, and curriculum mastery. Dictates leaderboard rank and user levels. XP is not an NFT or tradable token.
* **Gems**: In-app computational utility points. Can be earned through lessons, daily check-ins, or contests, and utilized within the platform for quiz battle wagers, contest entry fees, and streak freezes. Gems are computational gamification values (not NFTs, and not convertible/redeemable to external fiat/ERC-20 tokens).

***

## 2. Streaks & Daily Habits

* **Daily Activity Streak**: Incremented every 24-hour cycle upon lesson completion or quiz activity.
* **Bi-Weekly Streak Cycles**: Special multi-day reward boosts yielding extra gems and exclusive badge eligibility.

***

## 3. Badges & On-Chain Achievements

* Defined with unlock criteria (e.g., *Complete 10 Web3 Lessons*, *Win 5 Live Battles*).
* Tracked via `badge_progress` entity.
* Upon achievement, mints an on-chain **ERC-721 NFT Badge** to the student's connected address.

***

## 4. Leaderboard System

* **Timeframes**: Weekly, Monthly, and All-Time.
* **Caching**: Cached in Redis with fast zset scoring for instantaneous sub-millisecond retrieval.
* **Archival**: Background crons take periodic historical snapshots into `leaderboard_weekly_history` and `leaderboard_monthly_history`.

***

## 5. Quiz Battles (Real-time 1-v-1)

* Matchmaking engine with bot fallback (`QuizBattleBotService`).
* WebSocket communication through `QuizBattleGateway`.
* Timed rounds with synchronized question delivery and score tallying.