OpenLearnX/DOCUMENTATION.md

OpenLearnX - Comprehensive Project Documentation

📋 Table of Contents

1. Project Overview
2. Core Features
3. Architecture
4. Technology Stack
5. Project Structure
6. Smart Contracts
7. Backend Services
8. Frontend Application
9. Database Schema
10. API Documentation
11. Setup & Installation
12. Deployment
13. Security Features
14. Contributing

---

🎯 Project Overview

OpenLearnX is a cutting-edge, decentralized learning and assessment platform that revolutionizes how learners acquire, demonstrate, and verify their skills. Built on Web3 technologies, it combines adaptive learning algorithms, real-time feedback systems, and blockchain-based certification to create a transparent, verifiable, and personalized educational experience.

Vision

To democratize education by providing learners with:

• Personalized, adaptive learning experiences that scale with their skill level
• Instant, actionable feedback on their performance
• Immutable, blockchain-verified certificates that employers can trust
• Full ownership of their learning data through decentralized storage

Problem It Solves

1. Traditional Credentials Are Unverifiable: Paper certificates and digital badges can be forged
2. One-Size-Fits-All Learning: Static courses don't adapt to individual learner needs
3. Delayed Feedback: Students wait days or weeks for assessment results
4. Data Ownership: Learners don't control their educational records
5. Skill Verification: Employers struggle to verify claimed skills

---

✨ Core Features

1. Adaptive Learning System

• Dynamic Difficulty Adjustment: Questions adapt in real-time based on learner performance
• Personalized Learning Paths: AI-driven recommendation engine suggests optimal learning sequences
• Skill Gap Analysis: Identifies weaknesses and focuses learning where it's needed most
• Progressive Difficulty Curve: Gradually increases challenge as competency improves

2. Instant Feedback & Assessment

• Real-Time Code Execution: Run and test code in multiple programming languages
• Immediate Results: Get instant feedback on quiz answers and code submissions
• Detailed Explanations: Understand why answers are correct or incorrect
• Performance Analytics: Track progress over time with comprehensive metrics

3. Blockchain Certificates (NFT)

• ERC-721 NFT Certificates: Each certificate is a unique, non-transferable NFT
• On-Chain Verification: Anyone can verify certificate authenticity on the blockchain
• IPFS Metadata Storage: Certificate details stored on decentralized storage
• Permanent Record: Certificates cannot be revoked or altered once minted
• Wallet Integration: MetaMask wallet connects learners to their certificates

4. Comprehensive Dashboard

• Student Dashboard:
  • Progress tracking across multiple subjects
  • Competency radar charts showing skill distribution
  • Certificate gallery with blockchain verification
  • Learning history and timeline
• Instructor Dashboard:
  • Class performance analytics
  • Student progress monitoring
  • Assessment creation and management
  • Bias detection in grading

5. Multi-Language Code Compiler

• Supported Languages: Python, JavaScript, Java, C++, C, Go, Rust, and more
• Secure Execution: Sandboxed environment with resource limits
• Real-Time Output: See compilation errors and execution results instantly
• Test Cases: Automated testing against predefined test cases

6. AI-Powered Quiz Generation

• LLM Integration: Uses machine learning to generate contextual questions
• Adaptive Question Selection: Picks questions based on difficulty and topic
• Auto-Grading: Automated evaluation of multiple-choice and coding questions
• Question Banking: Extensive library of pre-validated questions

7. Peer Review System

• Collaborative Learning: Students review each other's work
• Bias Detection: AI monitors for grading bias and inconsistencies
• Portfolio Building: Showcase best work for potential employers
• Anonymous Reviews: Optional anonymity to reduce bias

8. Decentralized Chat

• Peer-to-Peer Communication: Built on blockchain smart contracts
• Study Groups: Create topic-based discussion channels
• Encrypted Messages: Private, secure communication
• Persistent History: Chat logs stored on-chain

---

🏗 Architecture

OpenLearnX follows a modern microservices architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend Layer                           │
│  (Next.js 14 + React + TypeScript + TailwindCSS)               │
│  - User Interface                                               │
│  - Wallet Integration (MetaMask)                                │
│  - Real-time Updates                                            │
└────────────────────────┬───────────────────────────────────────┘
                         │ HTTPS/WebSocket
┌────────────────────────┴───────────────────────────────────────┐
│                      Backend Layer (Flask)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ Auth Service │  │ Quiz Service │  │ Cert Service │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ Compiler Svc │  │ Dashboard Svc│  │ Adaptive AI  │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└────────────────────────┬───────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
┌────────┴─────┐ ┌──────┴──────┐ ┌─────┴──────────┐
│   MongoDB    │ │  PostgreSQL │ │  Redis Cache   │
│  (Primary DB)│ │   (Future)  │ │  (Sessions)    │
└──────────────┘ └─────────────┘ └────────────────┘
         │
         │
┌────────┴─────────────────────────────────────────────┐
│           Blockchain Layer (Ethereum/Anvil)          │
│  ┌──────────────────────────────────────────┐        │
│  │  CertificateNFT Smart Contract (Solidity)│        │
│  │  - Mint NFT certificates                 │        │
│  │  - Verify authenticity                   │        │
│  │  - Track ownership                       │        │
│  └──────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────┘
         │
┌────────┴─────┐
│     IPFS     │  (Decentralized Storage)
│  Metadata    │  - Certificate details
│   Storage    │  - Learning records
└──────────────┘

Key Architectural Decisions

1. Microservices: Each major feature is a separate service for scalability
2. Blockchain Integration: Ethereum smart contracts for immutable certificates
3. Hybrid Storage: MongoDB for application data, IPFS for decentralized storage
4. JWT Authentication: Stateless authentication with wallet-based identity
5. Real-Time Processing: WebSocket connections for live updates
6. Containerization: Docker for consistent deployment across environments

---

🔧 Technology Stack

Frontend

• Framework: Next.js 14 (React 18)
• Language: TypeScript
• Styling: TailwindCSS
• UI Components: Radix UI, shadcn/ui
• State Management: React Context + Hooks
• Web3 Integration:
  • ethers.js / web3.js
  • MetaMask SDK
  • wagmi (React Hooks for Ethereum)
• Charts & Visualization: Chart.js, Recharts
• Forms: React Hook Form + Zod validation
• HTTP Client: Axios
• Animations: Framer Motion

Backend

• Framework: Flask 2.3.3 (Python)
• Async Support: asyncio, motor (async MongoDB driver)
• API Type: REST + WebSocket
• Authentication:
  • Flask-JWT-Extended
  • Wallet signature verification (Web3)
• CORS: Flask-CORS
• Environment: python-dotenv

Database

• Primary: MongoDB 6.0+
  • Document-based storage for flexible schemas
  • Collections: users, courses, quizzes, certificates, submissions
• Cache: Redis 7
  • Session management
  • Rate limiting
  • Temporary data storage
• Future: PostgreSQL (planned for relational data)

Blockchain

• Smart Contract Language: Solidity 0.8.19
• Development Framework: Foundry
  • forge (testing and building)
  • anvil (local Ethereum node)
  • cast (CLI for contract interaction)
• Smart Contract Standards:
  • ERC-721 (NFT certificates)
  • OpenZeppelin contracts (security-audited base contracts)
• Network:
  • Local: Anvil (development)
  • Production: Ethereum mainnet / L2 solutions (Polygon, Arbitrum)

Machine Learning

• Framework: TensorFlow 2.17, Keras 3.2
• Data Processing: NumPy, Pandas, scikit-learn
• NLP: (for question generation and analysis)
• Adaptive Algorithm: Custom implementation with reinforcement learning principles

DevOps

• Containerization: Docker, Docker Compose
• CI/CD: GitHub Actions (implied)
• Deployment:
  • Single-server: deploy-single.sh script
  • Container orchestration ready
• Monitoring: Application logs, TensorFlow metrics

Security

• Encryption: PyCryptodome (AES encryption)
• Password Hashing: passlib with bcrypt
• JWT: PyJWT with cryptographic signatures
• Web3 Security: eth-account for signature verification
• Secure Code Execution: Sandboxed Docker containers for code compilation

---

📁 Project Structure

OpenLearnX/
├── backend/                      # Flask backend application
│   ├── main.py                   # Application entry point
│   ├── requirements.txt          # Python dependencies
│   │
│   ├── contracts/                # Solidity smart contracts
│   │   └── CertificateNFT.sol   # ERC-721 NFT certificate contract
│   │
│   ├── routes/                   # API route handlers
│   │   ├── auth.py              # Authentication endpoints
│   │   ├── quizzes.py           # Quiz management
│   │   ├── adaptive_quiz.py     # Adaptive testing
│   │   ├── certificate.py       # NFT certificate minting
│   │   ├── dashboard.py         # Analytics and dashboards
│   │   ├── compiler.py          # Code compilation service
│   │   ├── coding.py            # Coding challenges
│   │   ├── exam.py              # Examination system
│   │   ├── courses.py           # Course management
│   │   ├── admin.py             # Admin panel
│   │   └── test_flow.py         # Testing workflows
│   │
│   ├── services/                 # Business logic layer
│   │   ├── ai_quiz_service.py   # AI-powered quiz generation
│   │   ├── adaptive_quiz_service.py  # Adaptive algorithm
│   │   ├── compiler_service.py  # Code compilation logic
│   │   ├── real_compiler_service.py  # Real code execution
│   │   ├── dashboard_service.py # Dashboard data aggregation
│   │   └── wallet_service.py    # Web3 wallet interactions
│   │
│   ├── models/                   # Data models
│   │   ├── user.py              # User data model
│   │   ├── certificate.py       # Certificate model
│   │   └── dashboard_models.py  # Dashboard data structures
│   │
│   ├── utils/                    # Utility functions
│   │   └── adaptive_engine.py   # Adaptive learning engine
│   │
│   ├── scripts/                  # Deployment and utility scripts
│   │   └── deploy.py            # Smart contract deployment
│   │
│   ├── llmtrain/                 # ML model training
│   ├── cache/                    # Temporary cache
│   ├── mongo_service.py         # MongoDB connection service
│   ├── web3_service.py          # Web3 blockchain service
│   ├── quiz_master.py           # Quiz orchestration
│   ├── seed_courses.py          # Database seeding
│   │
│   ├── foundry.toml             # Foundry configuration
│   ├── deployment.json          # Contract deployment info
│   └── Dockerfile               # Backend container config
│
├── frontend/                     # Next.js frontend application
│   ├── app/                     # Next.js 14 app directory
│   │   ├── page.tsx             # Home page
│   │   ├── layout.tsx           # Root layout
│   │   ├── globals.css          # Global styles
│   │   │
│   │   ├── auth/                # Authentication pages
│   │   ├── dashboard/           # Dashboard pages
│   │   ├── certificate/         # Certificate gallery
│   │   ├── courses/             # Course browsing
│   │   ├── coding/              # Code challenges
│   │   ├── compiler/            # Online compiler
│   │   ├── adaptive-quiz/       # Adaptive tests
│   │   ├── join-test/           # Test joining flow
│   │   └── admin/               # Admin panel
│   │
│   ├── components/              # Reusable React components
│   │   └── ui/                  # shadcn/ui components
│   │
│   ├── context/                 # React Context providers
│   ├── hooks/                   # Custom React hooks
│   ├── lib/                     # Utility libraries
│   ├── styles/                  # Additional styles
│   │
│   ├── package.json             # Node.js dependencies
│   ├── tsconfig.json            # TypeScript configuration
│   ├── tailwind.config.ts       # TailwindCSS configuration
│   ├── next.config.mjs          # Next.js configuration
│   └── components.json          # shadcn/ui config
│
├── chatApp/                      # Decentralized chat feature
│   ├── chatApp.sol              # Chat smart contract
│   ├── index.html               # Chat interface
│   ├── account.html             # Account management
│   └── styles.css               # Chat styling
│
├── .wake/                        # Wake AI agent configuration
│
├── docker-compose.yml           # Multi-container orchestration
├── Dockerfile                   # Main application container
├── deploy-single.sh             # Single-server deployment script
├── requirements.txt             # Python dependencies (root)
├── README.md                    # Project overview
├── steps.md                     # Setup instructions
├── .gitignore                   # Git ignore rules
├── .dockerignore                # Docker ignore rules
└── .gitmodules                  # Git submodules (OpenZeppelin)

---

📜 Smart Contracts

CertificateNFT Contract

Purpose: Issue tamper-proof, blockchain-verified certificates as NFTs.

Key Features:

• ERC-721 compliant (standard NFT)
• Stores certificate metadata on-chain
• Tracks certificate ownership
• Verifiable by anyone on the blockchain

Contract Structure:

contract CertificateNFT is ERC721, ERC721URIStorage, Ownable {
    struct Certificate {
        string subject;        // Course/subject name
        string studentName;    // Learner name
        uint256 score;         // Achievement score
        uint256 timestamp;     // Issue date
        bool verified;         // Verification status
    }
    
    // Main functions:
    - mintCertificate(address to, string tokenURI)
    - mintCertificateWithDetails(...)
    - getCertificate(uint256 tokenId)
    - getUserCertificates(address user)
    - verifyCertificate(uint256 tokenId)
}

Key Functions:

1. mintCertificate: Creates a basic certificate NFT

   • Only owner (platform) can mint
   • Assigns to learner's wallet
   • Returns token ID

2. mintCertificateWithDetails: Creates detailed certificate

   • Includes subject, name, score
   • Timestamp automatically set
   • Emits CertificateMinted event

3. verifyCertificate: Public verification

   • Anyone can check authenticity
   • Returns verification status

4. getUserCertificates: Get all certificates for a wallet

   • Returns array of token IDs
   • Used for portfolio display

Deployment:

• Deployed using Foundry (forge)
• Uses OpenZeppelin audited base contracts
• Deployed on local Anvil node for development
• Ready for mainnet/L2 deployment

---

🖥 Backend Services

1. Authentication Service (routes/auth.py)

Endpoints:

• POST /api/auth/nonce - Generate nonce for wallet signature
• POST /api/auth/verify - Verify wallet signature and issue JWT
• POST /api/auth/register - Register new user with wallet
• GET /api/auth/profile - Get user profile (requires JWT)

Authentication Flow:

1. User connects MetaMask wallet
2. Frontend requests nonce from backend
3. User signs nonce with private key
4. Backend verifies signature matches wallet address
5. Backend issues JWT token
6. JWT used for subsequent requests

Security:

• Wallet-based authentication (no passwords)
• Time-limited nonces (prevent replay attacks)
• JWT with expiration
• Signature verification using eth-account

2. Quiz Service (routes/quizzes.py)

Features:

• Create, read, update, delete quizzes
• Multiple question types (MCQ, coding, essay)
• Auto-grading for objective questions
• Manual grading interface for subjective questions
• Quiz attempt tracking
• Time limits and deadlines

Endpoints:

• POST /api/quizzes - Create quiz
• GET /api/quizzes - List all quizzes
• GET /api/quizzes/:id - Get quiz details
• POST /api/quizzes/:id/attempt - Submit quiz attempt
• GET /api/quizzes/:id/results - Get results

3. Adaptive Quiz Service (routes/adaptive_quiz.py)

Adaptive Algorithm:

• Uses Item Response Theory (IRT)
• Adjusts question difficulty based on performance
• Estimates learner ability in real-time
• Provides personalized question selection

How It Works:

1. Start with medium difficulty question
2. If correct → increase difficulty
3. If incorrect → decrease difficulty
4. Track ability estimate (theta)
5. Select next question optimally for ability level
6. Repeat until convergence or question limit

Endpoints:

• POST /api/adaptive-quiz/start - Start adaptive test
• POST /api/adaptive-quiz/answer - Submit answer, get next question
• GET /api/adaptive-quiz/results - Final results and ability estimate

4. Certificate Service (routes/certificate.py)

Certificate Issuance Flow:

1. User completes quiz/course
2. Backend verifies completion and score
3. Generate certificate metadata (JSON)
4. Upload metadata to IPFS
5. Call smart contract to mint NFT
6. Store transaction hash in database
7. Return certificate to user

Endpoints:

• POST /api/certificates/mint - Mint new certificate
• GET /api/certificates/:id - Get certificate details
• GET /api/certificates/user/:wallet - Get user's certificates
• GET /api/certificates/verify/:tokenId - Verify certificate on blockchain

IPFS Integration:

• Metadata stored on IPFS for permanence
• Contains: name, subject, score, issue date, image
• IPFS hash stored in smart contract
• Ensures data can't be lost or altered

5. Compiler Service (routes/compiler.py)

Supported Languages:

• Python (3.x)
• JavaScript (Node.js)
• Java
• C++, C
• Go
• Rust
• Ruby
• PHP

Execution Flow:

1. Receive code and language from frontend
2. Create isolated Docker container
3. Write code to file inside container
4. Compile (if needed)
5. Execute with resource limits (CPU, memory, time)
6. Capture stdout, stderr
7. Return output to user
8. Clean up container

Security Features:

• Sandboxed execution (Docker)
• Resource limits (prevent infinite loops)
• Network isolation
• No file system access outside container
• Timeout enforcement

Endpoints:

• POST /api/compiler/run - Execute code
• POST /api/compiler/test - Run against test cases

6. Dashboard Service (routes/dashboard.py)

Analytics Provided:

• Overall progress percentage
• Competency radar chart (skill distribution)
• Time series of performance
• Subject-wise breakdown
• Recent activity timeline
• Strengths and weaknesses

Student Dashboard:

• My courses and progress
• Recent quiz scores
• Certificates earned
• Upcoming deadlines
• Recommended next steps

Instructor Dashboard:

• Class average performance
• Student progress tracking
• Question statistics (difficulty, discrimination)
• Grading queue
• Bias detection alerts

Endpoints:

• GET /api/dashboard/student - Student analytics
• GET /api/dashboard/instructor - Instructor analytics
• GET /api/dashboard/competency - Competency mapping

7. AI Quiz Service (services/ai_quiz_service.py)

Question Generation:

• Uses TensorFlow models
• Generates contextual questions based on topic
• Validates question quality
• Creates distractors (wrong answers) for MCQs

Features:

• Topic-based generation
• Difficulty control
• Question type variety
• Quality scoring

---

🎨 Frontend Application

Key Pages

1. Home Page (app/page.tsx)

• Platform introduction
• Feature highlights
• Call to action (Connect Wallet)
• Statistics (users, certificates issued, courses)

2. Authentication (app/auth/)

• MetaMask connection
• Wallet signature verification
• User registration flow
• Profile management

3. Dashboard (app/dashboard/)

• Progress overview
• Recent activity
• Quick actions
• Performance charts

4. Courses (app/courses/)

• Course catalog
• Course details
• Enrollment
• Course progress

5. Adaptive Quiz (app/adaptive-quiz/)

• Quiz interface
• Real-time difficulty adjustment
• Instant feedback
• Progress indicator

6. Coding Challenges (app/coding/)

• Problem description
• Code editor (Monaco Editor)
• Test cases
• Submission and results

7. Online Compiler (app/compiler/)

• Multi-language support
• Live code execution
• Output display
• Error handling

8. Certificate Gallery (app/certificate/)

• User's certificates
• Blockchain verification
• Download/share options
• QR code for verification

9. Admin Panel (app/admin/)

• User management
• Course creation
• Quiz authoring
• Analytics and reports

Key Components

UI Components (shadcn/ui):

• Buttons, Cards, Dialogs
• Forms, Inputs, Selects
• Tables, Tabs, Toast notifications
• Accordions, Alerts, Avatars

Custom Components:

• WalletConnect: MetaMask integration
• QuestionCard: Quiz question display
• CodeEditor: Syntax-highlighted editor
• ProgressChart: Performance visualization
• CertificateCard: NFT certificate display

---

💾 Database Schema

MongoDB Collections

1. users

{
  "_id": ObjectId,
  "wallet_address": "0x...",
  "username": "string",
  "email": "string",
  "role": "student|instructor|admin",
  "created_at": ISODate,
  "profile": {
    "name": "string",
    "bio": "string",
    "avatar": "string"
  },
  "stats": {
    "quizzes_completed": 0,
    "certificates_earned": 0,
    "total_score": 0
  }
}

2. courses

{
  "_id": ObjectId,
  "title": "string",
  "description": "string",
  "instructor_id": ObjectId,
  "topics": ["array of strings"],
  "difficulty": "beginner|intermediate|advanced",
  "created_at": ISODate,
  "quizzes": ["array of quiz IDs"],
  "enrollments": 0
}

3. quizzes

{
  "_id": ObjectId,
  "course_id": ObjectId,
  "title": "string",
  "description": "string",
  "questions": [
    {
      "id": "string",
      "type": "mcq|coding|essay",
      "question": "string",
      "options": ["array"],
      "correct_answer": "string|array",
      "points": 0,
      "difficulty": 0.0-1.0
    }
  ],
  "time_limit": 3600,
  "passing_score": 70,
  "adaptive": true|false
}

4. quiz_attempts

{
  "_id": ObjectId,
  "quiz_id": ObjectId,
  "user_id": ObjectId,
  "started_at": ISODate,
  "completed_at": ISODate,
  "answers": [
    {
      "question_id": "string",
      "user_answer": "string",
      "is_correct": true|false,
      "points_earned": 0
    }
  ],
  "score": 0,
  "percentage": 0.0,
  "ability_estimate": 0.0,
  "passed": true|false
}

5. certificates

{
  "_id": ObjectId,
  "user_id": ObjectId,
  "wallet_address": "0x...",
  "course_id": ObjectId,
  "quiz_id": ObjectId,
  "token_id": 0,
  "transaction_hash": "0x...",
  "ipfs_hash": "string",
  "subject": "string",
  "score": 0,
  "issued_at": ISODate,
  "metadata": {
    "name": "string",
    "description": "string",
    "image": "string"
  }
}

---

🔌 API Documentation

Base URL

Development: http://localhost:5000/api
Production: https://your-domain.com/api

Authentication

All protected endpoints require JWT token in header:

Authorization: Bearer <jwt_token>

Common Response Format

{
  "success": true|false,
  "data": {},
  "message": "string",
  "error": "string" // only on failure
}

Endpoint Summary

Method	Endpoint	Description	Auth
Authentication
POST	/auth/nonce	Get nonce for wallet signature	No
POST	/auth/verify	Verify signature and get JWT	No
POST	/auth/register	Register new user	No
GET	/auth/profile	Get user profile	Yes
Quizzes
GET	/quizzes	List all quizzes	No
GET	/quizzes/:id	Get quiz details	Yes
POST	/quizzes/:id/attempt	Submit quiz attempt	Yes
GET	/quizzes/:id/results	Get quiz results	Yes
Adaptive Quiz
POST	/adaptive-quiz/start	Start adaptive test	Yes
POST	/adaptive-quiz/answer	Submit answer	Yes
GET	/adaptive-quiz/results	Get final results	Yes
Certificates
POST	/certificates/mint	Mint certificate	Yes
GET	/certificates/user/:wallet	Get user certificates	No
GET	/certificates/verify/:tokenId	Verify certificate	No
Compiler
POST	/compiler/run	Execute code	Yes
POST	/compiler/test	Run test cases	Yes
Dashboard
GET	/dashboard/student	Student analytics	Yes
GET	/dashboard/instructor	Instructor analytics	Yes
Courses
GET	/courses	List courses	No
GET	/courses/:id	Get course details	No
POST	/courses/:id/enroll	Enroll in course	Yes

---

⚙️ Setup & Installation

Prerequisites

• Operating System: Linux, macOS, or WSL (Windows Subsystem for Linux)
• Node.js: v18+ (for frontend)
• Python: 3.10+ (for backend)
• MongoDB: 6.0+ (database)
• Docker: 20.10+ (optional, for containerized deployment)
• Git: For cloning repository
• MetaMask: Browser extension for Web3

Step-by-Step Installation

1. Install Foundry (Blockchain Development Toolkit)

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

# Install Foundry toolchain
foundryup

# Verify installation
forge --version
anvil --version
cast --version

2. Clone Repository

git clone https://github.com/th30d4y/OpenLearnX.git
cd OpenLearnX

3. Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env  # Create this if it doesn't exist

# Edit .env with your settings
nano .env

Required Environment Variables (.env):

# Flask
FLASK_APP=main.py
FLASK_ENV=development
SECRET_KEY=your-secret-key-here

# MongoDB
MONGODB_URI=mongodb://localhost:27017/openlearnx

# Redis (optional)
REDIS_URL=redis://localhost:6379

# Web3
WEB3_PROVIDER_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x... # Set after deploying contract

# IPFS (optional)
IPFS_GATEWAY=https://ipfs.io/ipfs/

# JWT
JWT_SECRET_KEY=your-jwt-secret
JWT_ACCESS_TOKEN_EXPIRES=3600

4. Start Local Blockchain

Terminal 1 - Run Anvil:

anvil --fork-url https://eth.merkle.io

This starts a local Ethereum node. Keep this running.

Output:

Available Accounts
==================
(0) 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
(1) 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH)
...

Private Keys
==================
(0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
...

Chain ID
==================
31337

5. Deploy Smart Contract

Terminal 2:

cd backend
source venv/bin/activate

# Deploy contract
python3 scripts/deploy.py

Output:

Deploying CertificateNFT contract...
Contract deployed at: 0x5FbDB2315678afecb367f032d93F642f64180aa3
Transaction hash: 0x...

Important: Copy the contract address to your .env file:

CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3

6. Start Backend Server

Terminal 3:

cd backend
source venv/bin/activate

# Seed database (optional)
python3 seed_courses.py

# Start Flask app
python3 main.py

Output:

 * Running on http://127.0.0.1:5000
 * Running on http://192.168.x.x:5000

Test Backend:

# Health check
curl http://127.0.0.1:5000/

# Test nonce generation
curl -X POST http://127.0.0.1:5000/api/auth/nonce \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"}'

7. Install MongoDB

Linux (Arch):

yay -S mongodb-bin
sudo systemctl start mongodb
sudo systemctl enable mongodb
mongosh  # Test connection

macOS:

brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community
mongosh  # Test connection

Docker:

docker run -d -p 27017:27017 --name mongodb mongo:6

8. Frontend Setup

Terminal 4:

cd frontend

# Install dependencies
pnpm install
# or: npm install

# Copy environment template
cp .env.example .env.local

# Edit .env.local
nano .env.local

Frontend Environment Variables (.env.local):

NEXT_PUBLIC_API_URL=http://localhost:5000/api
NEXT_PUBLIC_CHAIN_ID=31337
NEXT_PUBLIC_CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
NEXT_PUBLIC_RPC_URL=http://127.0.0.1:8545

Start Frontend:

pnpm run dev
# or: npm run dev

Output:

▲ Next.js 14.0.0
- Local:        http://localhost:3000
- Network:      http://192.168.x.x:3000

9. Access Application

1. Open browser: http://localhost:3000
2. Install MetaMask extension if not already installed
3. Add local network to MetaMask:
   • Network Name: Anvil Local
   • RPC URL: http://127.0.0.1:8545
   • Chain ID: 31337
   • Currency Symbol: ETH
4. Import account using private key from Anvil
5. Connect wallet on homepage
6. Start learning!

---

🚀 Deployment

Docker Deployment

Option 1: Docker Compose (Recommended)

Includes: Application, MongoDB, Redis, all in one command

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Access:

• Application: http://localhost:80
• MongoDB: localhost:5432
• Redis: localhost:6379

Option 2: Single Container

# Build image
docker build -t openlearnx .

# Run container
docker run -d -p 80:80 \
  -e DATABASE_URL=mongodb://host.docker.internal:27017/openlearnx \
  -e CONTRACT_ADDRESS=0x... \
  --name openlearnx \
  openlearnx

Production Deployment

Prerequisites

• VPS or cloud server (AWS, DigitalOcean, etc.)
• Domain name
• SSL certificate (Let's Encrypt)

Deployment Script

The project includes deploy-single.sh for single-server deployment:

# Make script executable
chmod +x deploy-single.sh

# Run deployment
./deploy-single.sh

Script performs:

1. Updates system packages
2. Installs dependencies
3. Clones repository
4. Sets up Python environment
5. Installs Node.js packages
6. Configures MongoDB
7. Deploys smart contract
8. Starts services
9. Sets up Nginx reverse proxy
10. Configures SSL

Manual Production Setup

1. Server Setup:

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y python3 python3-pip nodejs npm mongodb nginx

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

2. Clone and Configure:

cd /opt
sudo git clone https://github.com/th30d4y/OpenLearnX.git
cd OpenLearnX

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install
npm run build

3. Deploy Contract (if using public network):

# Set up Ethereum node or use Alchemy/Infura
# Update deploy script with production network
cd backend
python3 scripts/deploy.py --network mainnet

4. Configure Nginx:

# /etc/nginx/sites-available/openlearnx
server {
    listen 80;
    server_name your-domain.com;

    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/openlearnx /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Setup SSL
sudo certbot --nginx -d your-domain.com

5. Process Management (systemd):

Backend service (/etc/systemd/system/openlearnx-backend.service):

[Unit]
Description=OpenLearnX Backend
After=network.target mongodb.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/OpenLearnX/backend
Environment="PATH=/opt/OpenLearnX/backend/venv/bin"
ExecStart=/opt/OpenLearnX/backend/venv/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target

Frontend service (/etc/systemd/system/openlearnx-frontend.service):

[Unit]
Description=OpenLearnX Frontend
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/OpenLearnX/frontend
Environment="NODE_ENV=production"
ExecStart=/usr/bin/npm start
Restart=always

[Install]
WantedBy=multi-user.target

# Start services
sudo systemctl daemon-reload
sudo systemctl enable openlearnx-backend openlearnx-frontend
sudo systemctl start openlearnx-backend openlearnx-frontend

---

🔒 Security Features

1. Wallet-Based Authentication

• No passwords to leak or hack
• Cryptographic signature verification
• User owns their identity (wallet)
• Prevents phishing attacks

2. Smart Contract Security

• Uses OpenZeppelin audited contracts
• Access control (only owner can mint)
• Non-transferable certificates (soulbound tokens)
• Immutable once minted

3. Code Execution Sandbox

• Docker containerization
• Resource limits (CPU, memory, time)
• No network access
• Read-only file system
• Process isolation

4. Data Encryption

• AES encryption for sensitive data
• HTTPS/TLS in production
• JWT with signature verification
• Encrypted database connections

5. Input Validation

• All inputs sanitized
• SQL injection prevention (using ORM)
• XSS protection
• CSRF tokens

6. Rate Limiting

• API rate limits (Redis)
• Prevents DDoS attacks
• Per-user request limits
• Gradual backoff

7. Secure File Handling

• File type validation
• Size limits
• Virus scanning (production)
• Isolated storage

8. Audit Logging

• All critical actions logged
• User activity tracking
• Security event monitoring
• Compliance ready

---

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Workflow

1. Fork the Repository

   # Click "Fork" on GitHub
   git clone https://github.com/YOUR_USERNAME/OpenLearnX.git
   

2. Create Feature Branch

   git checkout -b feature/your-feature-name
   

3. Make Changes

   • Write clean, documented code
   • Follow existing code style
   • Add tests for new features
   • Update documentation

4. Test Locally

   # Backend tests
   cd backend
   pytest
   
   # Frontend tests
   cd frontend
   npm test
   

5. Commit Changes

   git add .
   git commit -m "feat: add new adaptive algorithm"
   

   Commit Message Format:

   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation changes
   • style: - Code style changes
   • refactor: - Code refactoring
   • test: - Test changes
   • chore: - Build/tool changes

6. Push and Create PR

   git push origin feature/your-feature-name
   # Open Pull Request on GitHub
   

Code Style Guidelines

Python:

• Follow PEP 8
• Use type hints
• Write docstrings for functions
• Maximum line length: 88 characters (Black formatter)

TypeScript/React:

• Use TypeScript strict mode
• Functional components with hooks
• ESLint and Prettier compliant
• Meaningful component names

Smart Contracts:

• Follow Solidity style guide
• Extensive comments
• Gas optimization
• Security first

Areas for Contribution

• 🐛 Bug fixes
• ✨ New features
• 📚 Documentation improvements
• 🌐 Translations/i18n
• 🎨 UI/UX enhancements
• ⚡ Performance optimizations
• 🧪 Test coverage
• 🔒 Security audits

---

📊 Project Status & Roadmap

Current Status

✅ Alpha Release - Core features functional, under active development

Completed Features

• Wallet authentication
• Basic quiz system
• Adaptive testing algorithm
• NFT certificate minting
• Multi-language compiler
• Student dashboard
• Course management
• Admin panel

In Progress

• AI question generation refinement
• Peer review system
• Enhanced analytics
• Mobile app (React Native)

Planned Features

• Live proctoring for exams
• Video lessons integration
• Gamification (badges, leaderboards)
• Social features (study groups, forums)
• Marketplace for courses
• Integration with job platforms
• Multi-language support (i18n)
• Offline mode (PWA)
• AI tutor chatbot
• Advanced bias detection

---

📞 Support & Community

Getting Help

• 📖 Documentation: This file and inline code comments
• 💬 Discussions: GitHub Discussions tab
• 🐛 Issues: GitHub Issues for bug reports
• 📧 Email: [Project maintainer email]

Community Guidelines

• Be respectful and inclusive
• Help others learn and grow
• Share knowledge freely
• Report security issues privately

---

📄 License

[Include license information here - e.g., MIT, Apache 2.0]

---

🙏 Acknowledgments

• OpenZeppelin: Secure smart contract libraries
• Foundry: Blazing fast Ethereum development toolkit
• Next.js: React framework for production
• TensorFlow: Machine learning framework
• MongoDB: Flexible database solution
• shadcn/ui: Beautiful component library
• All Contributors: Thank you for making OpenLearnX better!

---

📈 Statistics

• Lines of Code: ~8,000+ (backend Python)
• Smart Contracts: 1 deployed (CertificateNFT)
• API Endpoints: 30+
• Supported Languages: 8+ (compiler)
• Dependencies:
  • Python: 50+ packages
  • Node.js: 60+ packages
• Database Collections: 6 primary collections

---

🔮 Vision for the Future

OpenLearnX aims to become the de facto standard for verifiable online learning. We envision a world where:

1. Every learner owns their educational data and credentials
2. Employers can instantly verify candidate skills
3. Education is accessible, personalized, and continuous
4. Certificates are globally recognized and tamper-proof
5. Learning adapts to individual needs in real-time

Join us in revolutionizing education! 🚀

---

Last Updated: 2026-01-31 Version: 1.0.0 Maintainer: OpenLearnX Team