# LearnWay Backend

## Docs

- [Introduction](https://docs.learnway.xyz/introduction.md): LearnWay is a gamified, blockchain-integrated Learning Management System (LMS) backend powering education with XP, gems, badges, live competitions, and real on-chain rewards.
- [Quick Start](https://docs.learnway.xyz/quickstart.md): Get the LearnWay backend running locally in under 10 minutes.
- [Environment Variables Reference](https://docs.learnway.xyz/guides/environment-variables.md): Comprehensive list of all required and optional environment variables for LearnWay Backend.
- [System Architecture & Ecosystem Topology](https://docs.learnway.xyz/architecture/overview.md): Full-system architecture map covering mobile client, core backend API, smart contracts, Alto ERC-4337 bundler, and transaction relayer.
- [In-House Systems vs. Third-Party Integrations](https://docs.learnway.xyz/architecture/third-party-vs-inhouse.md): Comprehensive breakdown of LearnWay proprietary in-house software versus integrated third-party infrastructure and external APIs.
- [Mobile Client Architecture](https://docs.learnway.xyz/architecture/mobile-client.md): Architecture, screen navigation, AI Mentor integration, and Web3 wallet UX for the LearnWay mobile client (learnway-mobile/).
- [Blockchain Architecture Overview](https://docs.learnway.xyz/architecture/blockchain/overview.md): High-level architecture of LearnWay on-chain ecosystem: Dual execution model, Smart Contracts on Lisk L2, Account Abstraction, Relayer, and Goldsky Indexer.
- [ERC-4337 Account Abstraction & Paymaster](https://docs.learnway.xyz/architecture/blockchain/account-abstraction.md): Client-side smart accounts, VerifyingPaymaster policy engine, allowed transaction selectors, sponsored token contracts, and Alto Bundler.
- [Smart Contracts Suite](https://docs.learnway.xyz/architecture/blockchain/smart-contracts.md): Complete Lisk L2 smart contract architecture (learnway_onchain_infrastructure/): LearnWayAdmin, LearnWayManager, LearnwayXPGemsContract (XP & Gems state engines), Badges NFT, and Certificates.
- [Transaction Processor (Backend Relayer)](https://docs.learnway.xyz/architecture/blockchain/transaction-processor.md): On-chain transaction execution engine (learnway-transaction-processor/), LearnWayManager interaction, nonce management, and gas escalation.
- [Goldsky Indexer & Transaction History](https://docs.learnway.xyz/architecture/blockchain/indexer-goldsky.md): Subgraph indexing pipeline (transactions_apiv2/), Goldsky block streaming, and high-performance wallet ledger querying on Lisk L2.
- [Microservices Architecture Overview](https://docs.learnway.xyz/architecture/microservices/overview.md): Architecture of standalone microservices in the LearnWay ecosystem: AI Microservice and Notification Microservice.
- [AI Microservice](https://docs.learnway.xyz/architecture/microservices/ai-service.md): Standalone AI inference service (learnway-ai-service/), Google Gemini models, prompt context injection, and Redis response caching.
- [Notification Microservice](https://docs.learnway.xyz/architecture/microservices/notification-service.md): Notification delivery architecture (learnway-notification-service/), Firebase Cloud Messaging (FCM), in-app inbox, and Resend email pipelines.
- [Authentication & Security](https://docs.learnway.xyz/architecture/auth.md): Comprehensive guide to authentication mechanisms, JWT token lifecycle, multi-factor auth (TOTP), wallet PINs, and security policies.
- [Courses & Lessons System](https://docs.learnway.xyz/architecture/courses-and-lessons.md): Hierarchical educational content structure: Learning Paths, Courses, Lessons, Interactive Slides, and Progression Tracking.
- [Learning Paths & Roadmaps](https://docs.learnway.xyz/architecture/learning-paths.md): Structured career roadmaps, adaptive AI curriculum recommendations, and micro-skill progressions.
- [Gamification & Competitions](https://docs.learnway.xyz/architecture/gamification.md): Gamification engine: Experience Points (XP), Gems, Streaks, Badges, Leaderboards, Contests, and Quiz Battles.
- [Payments & Fonbnk Integration](https://docs.learnway.xyz/architecture/payments.md): Fiat-to-Crypto On-Ramp and Crypto-to-Fiat Off-Ramp via Fonbnk, currency conversion, and webhook verification.
- [WebSockets & Real-time Events](https://docs.learnway.xyz/architecture/websockets.md): Socket.IO architecture, authentication handshakes, room partitioning, and real-time state synchronization.
- [Security & Data Compliance](https://docs.learnway.xyz/architecture/security-and-compliance.md): Data privacy standards (GDPR, NDPR, POPIA, LGPD), on-chain vs. off-chain PII separation, Right to Erasure, and security governance.
- [AI Governance, Safety & Accuracy](https://docs.learnway.xyz/architecture/ai-governance.md): Architectural guardrails, strict context grounding (RAG), deterministic caching, quality feedback loops, and circuit breaker governance in LearnWay AI.
- [Audit Trails & System Logging](https://docs.learnway.xyz/architecture/auditing-and-logging.md): Multi-layered auditing architecture in LearnWay: Admin audit logs, on-chain transaction tracking, reward ledgers, payment webhooks, AI interaction audits, and Sentry observability.
- [Local Development Setup](https://docs.learnway.xyz/guides/quickstart-local.md): Step-by-step instructions for running the development environment, seeding demo data, and testing features locally.
- [Social Login Integration](https://docs.learnway.xyz/guides/social-login.md): How to authenticate users using Google and Apple Sign-In with LearnWay Backend.
- [Token Refresh Guide](https://docs.learnway.xyz/guides/token-refresh.md): Handling JWT expiration, silent refresh patterns, and token renewal in client applications.
- [Swagger OpenAPI Documentation](https://docs.learnway.xyz/guides/swagger-ui.md): How to access and use the interactive Swagger documentation for both User and Admin API surfaces.
- [Mobile App Integration Guide](https://docs.learnway.xyz/guides/mobile-integration.md): Guidelines and best practices for integrating the LearnWay Flutter mobile application with the backend API.
- [ImageKit Media Management](https://docs.learnway.xyz/guides/imagekit.md): Handling profile avatars, course cover assets, certificate templates, and media transformations via ImageKit.
- [Admin Guide](https://docs.learnway.xyz/guides/admin-guide.md): Administrative operations: course management, user moderation, translations, revenue controls, and system monitoring.
- [App Version Control & Feature Flags](https://docs.learnway.xyz/guides/app-version-control.md): Managing minimum supported app versions, force-update prompts, and maintenance mode.
- [API Reference Overview](https://docs.learnway.xyz/api-reference/overview.md): Overview of LearnWay REST API v2 endpoints, authentication headers, error envelopes, and rate limits.
- [Register](https://docs.learnway.xyz/api-reference/auth/register.md): Register a new user account with email/password or initial account setup.
- [Login](https://docs.learnway.xyz/api-reference/auth/login.md): Authenticate with password, email OTP, or TOTP second factor.
- [Social Login](https://docs.learnway.xyz/api-reference/auth/social-login.md): Authenticate via Google or Apple OAuth tokens.
- [OTP Verification](https://docs.learnway.xyz/api-reference/auth/otp.md): Send and verify email OTP codes for signup, login, and password resets.
- [Token Refresh](https://docs.learnway.xyz/api-reference/auth/token-refresh.md): Rotate and obtain a fresh pair of JWT access and refresh tokens.
- [Password Management](https://docs.learnway.xyz/api-reference/auth/password-management.md): Request password reset emails, reset passwords via OTP, and change current passwords.
- [Wallet PIN](https://docs.learnway.xyz/api-reference/auth/wallet-pin.md): Set, verify, and reset security PINs for on-chain transactions and off-ramp operations.
- [TOTP Two-Factor Auth](https://docs.learnway.xyz/api-reference/auth/totp.md): Configure authenticator app 2FA (Google Authenticator, Authy) with QR codes and backup recovery codes.
- [List Courses](https://docs.learnway.xyz/api-reference/courses/list.md): Fetch published courses with optional filtering by learning path and user progress.
- [Course Detail & Lessons](https://docs.learnway.xyz/api-reference/courses/detail.md): Retrieve comprehensive course structure, modules, lessons, slides, and quizzes.
- [Course Progress & Enrollment](https://docs.learnway.xyz/api-reference/courses/progress.md): Enroll in courses, submit lesson completions, and earn XP and Gem rewards.
- [List Learning Paths](https://docs.learnway.xyz/api-reference/learning-paths/list.md): Fetch published learning paths, access entitlements, and course sequences.
- [Career Roadmaps](https://docs.learnway.xyz/api-reference/learning-paths/roadmap.md): Generate AI-powered career learning roadmaps and retrieve customized curricula.
- [AI Tutor](https://docs.learnway.xyz/api-reference/ai/tutor.md): Interactive AI tutor powered by Google Gemini with Redis response caching.
- [AI Assessment](https://docs.learnway.xyz/api-reference/ai/assessment.md): AI-driven project evaluation, code analysis, and personalized skill assessments.
- [Badges & On-Chain NFTs](https://docs.learnway.xyz/api-reference/gamification/badges.md): View user badge progression, track milestone completions, and claim NFT badges on Lisk L2.
- [Leaderboard](https://docs.learnway.xyz/api-reference/gamification/leaderboard.md): Global, weekly, monthly, and category-based leaderboard rankings.
- [Contests](https://docs.learnway.xyz/api-reference/gamification/contests.md): Time-limited competitions, entry fees, quiz submission, and prize distribution.
- [Quiz Battles](https://docs.learnway.xyz/api-reference/gamification/quiz-battles.md): Real-time 1v1 PvP quiz battles with matchmaking, bot fallbacks, and gem stakes.
- [Challenges & Streaks](https://docs.learnway.xyz/api-reference/gamification/challenges.md): Daily learning streaks, time-based challenges, and bonus reward claiming.
- [Projects & Capstones](https://docs.learnway.xyz/api-reference/projects/overview.md): Course capstone projects, draft saves, project submissions, and automated AI code evaluations.
- [Promotions & Banners](https://docs.learnway.xyz/api-reference/promotions/overview.md): Fetch targeted popup and banner campaigns and report client engagement events.
- [Payments Overview](https://docs.learnway.xyz/api-reference/payments/overview.md): Overview of LearnWay fiat-to-crypto on-ramps, off-ramps, mobile money, and airtime rails.
- [Exchange Rates](https://docs.learnway.xyz/api-reference/payments/exchange-rates.md): Real-time fiat-to-USDT conversion rates for Fonbnk-supported currencies.
- [On-Ramp](https://docs.learnway.xyz/api-reference/payments/on-ramp.md): Convert local fiat, airtime, or mobile money into crypto tokens and gems.
- [Off-Ramp](https://docs.learnway.xyz/api-reference/payments/off-ramp.md): Withdraw on-chain crypto rewards into local bank accounts, mobile money, or airtime.
- [Blockchain Wallet & Balances](https://docs.learnway.xyz/api-reference/blockchain/wallet.md): Query on-chain smart wallet balances, link external addresses, and gasless transaction handling.
- [Paymaster (Gasless Transactions)](https://docs.learnway.xyz/api-reference/blockchain/paymaster.md): ERC-7677 compatible Paymaster JSON-RPC service for sponsoring ERC-4337 Smart Account transactions.
- [Certificates (NFTs)](https://docs.learnway.xyz/api-reference/blockchain/certificates.md): Mint and verify soulbound NFT course completion certificates on-chain.
- [Subscriptions Overview](https://docs.learnway.xyz/api-reference/subscriptions/overview.md): Manage user premium subscriptions, RevenueCat mobile receipts, and feature gating.
- [Notifications Overview](https://docs.learnway.xyz/api-reference/notifications/overview.md): Push notifications via Firebase Cloud Messaging (FCM), in-app inbox, and read receipts.
- [User Profile](https://docs.learnway.xyz/api-reference/user/profile.md): Fetch user profiles, update personal details, change avatars, and track learning stats.
- [Referrals](https://docs.learnway.xyz/api-reference/user/referrals.md): Generate referral links, track invited referees, and calculate earned referral commissions.
- [Webhooks](https://docs.learnway.xyz/api-reference/webhooks/overview.md): Inbound webhook ingestion for blockchain smart contract events, Fonbnk payments, and RevenueCat subscriptions.

## OpenAPI Specs

- [openapi](https://docs.learnway.xyz/api-reference/openapi.json)