0x5t4l1n/OpenLearnX
1
0
Fork 0
mirror of https://github.com/th30d4y/OpenLearnX.git synced 2026-05-27 19:56:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1 from th30d4y/copilot/get-project-details

Browse Source 
Add comprehensive project documentation
This commit is contained in:
Stalin
2026-01-31 22:15:44 +05:30
committed by GitHub
parent 5c416361b4 883368b6d0
commit d5c7a2908b
5 changed files with 2561 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE.md
+327
View File
@@ -0,0 +1,327 @@
# OpenLearnX - Architecture Diagram
## System Architecture
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ USER INTERFACE LAYER ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
│
┌───────────────────────┼───────────────────────┐
│ │ │
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Web Browser │ │ Mobile App │ │ MetaMask │
│ (Next.js) │ │ (Planned) │ │ Wallet │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
└──────────────────────┴───────────────────────┘
│
HTTPS / WebSocket
│
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▼━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ BACKEND API LAYER (Flask) ┃
┃ ┃
┃ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┃
┃ │ Auth Service │ │ Quiz Service │ │ Cert Service │ ┃
┃ │ │ │ │ │ │ ┃
┃ │ - JWT Auth │ │ - MCQ │ │ - NFT Mint │ ┃
┃ │ - Wallet │ │ - Adaptive │ │ - IPFS │ ┃
┃ │ - Nonce │ │ - Grading │ │ - Verify │ ┃
┃ └──────────────┘ └──────────────┘ └──────────────┘ ┃
┃ ┃
┃ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┃
┃ │ Compiler Svc │ │ Dashboard Svc│ │ Adaptive AI │ ┃
┃ │ │ │ │ │ │ ┃
┃ │ - Python │ │ - Analytics │ │ - IRT │ ┃
┃ │ - JavaScript │ │ - Progress │ │ - ML Models │ ┃
┃ │ - C++/Java │ │ - Competency │ │ - Question │ ┃
┃ │ - Docker │ │ - Reports │ │ Selection │ ┃
┃ └──────────────┘ └──────────────┘ └──────────────┘ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┬━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
┏━━━━━━━━▼━━━━━━━━┓ ┏━━━━━━━━━━▼━━━━━━━━━┓ ┏━━━━━━━━━▼━━━━━━━┓
┃ Data Storage ┃ ┃ Cache Layer ┃ ┃ ML Services ┃
┃ ┃ ┃ ┃ ┃ ┃
┃ ┌───────────┐ ┃ ┃ ┌──────────────┐ ┃ ┃ ┌───────────┐ ┃
┃ │ MongoDB │ ┃ ┃ │ Redis │ ┃ ┃ │TensorFlow │ ┃
┃ │ │ ┃ ┃ │ │ ┃ ┃ │ │ ┃
┃ │ - Users │ ┃ ┃ │ - Sessions │ ┃ ┃ │ - Models │ ┃
┃ │ - Courses │ ┃ ┃ │ - Cache │ ┃ ┃ │ - Training│ ┃
┃ │ - Quizzes │ ┃ ┃ │ - Rate Limit │ ┃ ┃ │ - Predict │ ┃
┃ │ - Certs │ ┃ ┃ └──────────────┘ ┃ ┃ └───────────┘ ┃
┃ └───────────┘ ┃ ┗━━━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━┛
┗━━━━━━━━━━━━━━━━━┛
│
┏━━━━━━━━▼━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ BLOCKCHAIN LAYER (Ethereum) ┃
┃ ┃
┃ ┌────────────────────────────────────────────────────────────────┐ ┃
┃ │ CertificateNFT Smart Contract (Solidity) │ ┃
┃ │ │ ┃
┃ │ Functions: Data Structures: │ ┃
┃ │ • mintCertificate() • ERC-721 NFT │ ┃
┃ │ • mintCertificateWithDetails() • Certificate struct │ ┃
┃ │ • getCertificate() • userCertificates mapping │ ┃
┃ │ • verifyCertificate() • certificates mapping │ ┃
┃ │ • getUserCertificates() │ ┃
┃ └────────────────────────────────────────────────────────────────┘ ┃
┃ ┃
┃ Deployed on: ┃
┃ • Local: Anvil (Development) ┃
┃ • Production: Ethereum Mainnet / L2 (Polygon, Arbitrum) ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┬━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
│
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▼━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ DECENTRALIZED STORAGE LAYER (IPFS) ┃
┃ ┃
┃ Certificate Metadata: ┃
┃ • Student name, subject, score ┃
┃ • Issue date, institution ┃
┃ • Certificate image/PDF ┃
┃ • Immutable and permanent storage ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```
## Component Interactions
### 1. Authentication Flow
```
User → MetaMask → Nonce Request → Backend
↓
Sign Nonce
↓
Backend → Verify Signature → Issue JWT → User
```
### 2. Quiz Taking Flow
```
User → Start Quiz → Backend (Select Questions)
↓
Adaptive Algorithm (AI)
↓
Questions → User → Submit Answers
↓
Auto-Grade → Feedback
↓
Update Progress → Dashboard
```
### 3. Certificate Minting Flow
```
User Completes Quiz
↓
Backend Validates Score
↓
Generate Metadata
↓
Upload to IPFS
↓
Call Smart Contract
↓
Mint NFT on Blockchain
↓
Store Transaction Hash in MongoDB
↓
Certificate Available in User Wallet
```
### 4. Code Compilation Flow
```
User Writes Code → Frontend
↓
Backend Receives Code
↓
Create Docker Container
↓
Write Code, Compile, Execute
↓
Capture Output (with limits)
↓
Destroy Container
↓
Return Results → User
```
## Data Flow Diagram
```
┌─────────────┐
│ User │
│ (Student/ │
│ Instructor) │
└──────┬──────┘
│
├─── Authentication ──────────┐
│ │
│ ┌───────▼────────┐
│ │ JWT Token │
│ │ Generation │
│ └───────┬────────┘
│ │
├─── Take Quiz ───────────────┤
│ │
│ ┌───────▼────────┐
│ │ Question │
│ │ Selection │
│ │ (Adaptive AI) │
│ └───────┬────────┘
│ │
├─── Submit Answers ──────────┤
│ │
│ ┌───────▼────────┐
│ │ Grading │
│ │ Engine │
│ └───────┬────────┘
│ │
├─── View Results ────────────┤
│ │
│ ┌───────▼────────┐
│ │ Dashboard │
│ │ Analytics │
│ └───────┬────────┘
│ │
└─── Request Certificate ─────┤
│
┌───────▼────────┐
│ Blockchain │
│ NFT Minting │
└───────┬────────┘
│
┌───────▼────────┐
│ IPFS Upload │
└────────────────┘
```
## Technology Stack Map
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend Stack │
├─────────────────────────────────────────────────────────────┤
│ • Next.js 14 → React Framework │
│ • TypeScript → Type Safety │
│ • TailwindCSS → Styling │
│ • shadcn/ui → Component Library │
│ • ethers.js → Blockchain Interaction │
│ • Axios → HTTP Client │
│ • React Hook Form → Form Management │
│ • Chart.js → Data Visualization │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Backend Stack │
├─────────────────────────────────────────────────────────────┤
│ • Flask 2.3 → Web Framework │
│ • Python 3.10+ → Programming Language │
│ • TensorFlow 2.17 → Machine Learning │
│ • Motor/PyMongo → MongoDB Driver │
│ • Flask-JWT-Extended → Authentication │
│ • Web3.py → Blockchain Interaction │
│ • Docker → Code Sandboxing │
│ • Redis → Caching & Sessions │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Blockchain Stack │
├─────────────────────────────────────────────────────────────┤
│ • Solidity 0.8.19 → Smart Contract Language │
│ • Foundry → Development Toolkit │
│ - forge → Testing & Building │
│ - anvil → Local Ethereum Node │
│ - cast → CLI Tools │
│ • OpenZeppelin → Secure Contract Libraries │
│ • IPFS → Decentralized Storage │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Database Stack │
├─────────────────────────────────────────────────────────────┤
│ • MongoDB 6.0+ → Primary Database │
│ • Redis 7 → Cache & Sessions │
│ • PostgreSQL → Future Relational Data (Planned) │
└─────────────────────────────────────────────────────────────┘
```
## Security Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ Security Layers │
└──────────────────────────────────────────────────────────────┘
1. Authentication Layer
├── Wallet-based auth (MetaMask)
├── Cryptographic signatures
├── JWT tokens with expiration
└── Nonce-based replay protection
2. Authorization Layer
├── Role-based access control (RBAC)
├── Resource ownership validation
├── JWT claims verification
└── API route protection
3. Data Layer
├── AES encryption for sensitive data
├── HTTPS/TLS in production
├── Encrypted database connections
└── Input sanitization
4. Execution Layer
├── Docker sandboxing
├── Resource limits (CPU, memory, time)
├── Network isolation
└── Read-only file systems
5. Blockchain Layer
├── Smart contract access control
├── OpenZeppelin security standards
├── On-chain verification
└── Immutable records
6. Application Layer
├── CORS configuration
├── Rate limiting
├── Error handling
└── Audit logging
```
## Deployment Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Production Environment │
└─────────────────────────────────────────────────────────────┘
┌──────────────┐
│ CloudFlare │
│ CDN │
└──────┬───────┘
│
┌──────▼───────┐
│ Load │
│ Balancer │
└──────┬───────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ App │ │ App │ │ App │
│ Server 1 │ │ Server 2 │ │ Server 3 │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└──────────────────┼──────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ MongoDB │ │ Redis │ │ Ethereum │
│ Cluster │ │ Cluster │ │ Node │
└───────────┘ └───────────┘ └───────────┘
```
---
For detailed implementation, see [DOCUMENTATION.md](./DOCUMENTATION.md)
DOCS_INDEX.md
+223
View File
@@ -0,0 +1,223 @@
# 📖 OpenLearnX Documentation Index
Welcome to OpenLearnX! This index will help you navigate all the documentation.
## 🚀 Getting Started
**New to OpenLearnX?** Start here:
1. **[README.md](./README.md)** ⭐ START HERE
- Project overview
- Quick feature highlights
- Brief setup instructions
- Community links
2. **[QUICK_START.md](./QUICK_START.md)** ⚡ 15-MINUTE SETUP
- Step-by-step installation guide
- MetaMask configuration
- Testing your setup
- Troubleshooting common issues
## 📚 Deep Dive Documentation
**Ready to learn more?** Explore these comprehensive guides:
3. **[DOCUMENTATION.md](./DOCUMENTATION.md)** 📖 COMPLETE GUIDE
- Comprehensive project documentation (1,485 lines!)
- Detailed architecture explanation
- Technology stack deep dive
- API documentation
- Security features
- Production deployment guide
- Contributing guidelines
**Sections include:**
- Project Overview & Vision
- Core Features (8 major features)
- Architecture & Design
- Technology Stack Details
- Project Structure Walkthrough
- Smart Contract Documentation
- Backend Services Guide
- Frontend Application Guide
- Database Schema
- Complete API Reference
- Setup & Installation
- Deployment Strategies
- Security Features
- Contributing Guidelines
4. **[ARCHITECTURE.md](./ARCHITECTURE.md)** 🏗️ SYSTEM DESIGN
- Visual architecture diagrams
- Component interaction flows
- Data flow diagrams
- Technology stack maps
- Security architecture
- Deployment architecture
5. **[steps.md](./steps.md)** 🔧 DETAILED SETUP
- Original setup guide
- Terminal-by-terminal instructions
- Database configuration
- Frontend project structure
## 📋 Documentation Quick Reference
### By Audience
#### For Developers
- Start: [QUICK_START.md](./QUICK_START.md)
- Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
- API Reference: [DOCUMENTATION.md](./DOCUMENTATION.md#api-documentation)
- Contributing: [DOCUMENTATION.md](./DOCUMENTATION.md#contributing)
#### For Students/Users
- Overview: [README.md](./README.md)
- Getting Started: [QUICK_START.md](./QUICK_START.md)
- Features: [DOCUMENTATION.md](./DOCUMENTATION.md#core-features)
#### For Instructors
- Dashboard Guide: [DOCUMENTATION.md](./DOCUMENTATION.md#comprehensive-dashboard)
- Course Creation: [DOCUMENTATION.md](./DOCUMENTATION.md#backend-services)
- Analytics: [DOCUMENTATION.md](./DOCUMENTATION.md#dashboard-service)
#### For DevOps/SysAdmins
- Deployment: [DOCUMENTATION.md](./DOCUMENTATION.md#deployment)
- Docker Setup: [DOCUMENTATION.md](./DOCUMENTATION.md#docker-deployment)
- Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
- Security: [DOCUMENTATION.md](./DOCUMENTATION.md#security-features)
### By Topic
#### Setup & Installation
- Quick (15 min): [QUICK_START.md](./QUICK_START.md)
- Detailed: [steps.md](./steps.md)
- Production: [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment)
#### Architecture & Design
- Overview: [ARCHITECTURE.md](./ARCHITECTURE.md)
- System Design: [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture)
- Components: [DOCUMENTATION.md - Project Structure](./DOCUMENTATION.md#project-structure)
#### Features & Capabilities
- Feature List: [README.md - Core Features](./README.md#core-features)
- Detailed Features: [DOCUMENTATION.md - Core Features](./DOCUMENTATION.md#core-features)
- Use Cases: [README.md - Use Cases](./README.md#use-cases)
#### Development
- Tech Stack: [DOCUMENTATION.md - Technology Stack](./DOCUMENTATION.md#technology-stack)
- API Docs: [DOCUMENTATION.md - API Documentation](./DOCUMENTATION.md#api-documentation)
- Database: [DOCUMENTATION.md - Database Schema](./DOCUMENTATION.md#database-schema)
- Smart Contracts: [DOCUMENTATION.md - Smart Contracts](./DOCUMENTATION.md#smart-contracts)
#### Operations
- Deployment: [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment)
- Docker: [DOCUMENTATION.md - Docker Deployment](./DOCUMENTATION.md#docker-deployment)
- Security: [DOCUMENTATION.md - Security Features](./DOCUMENTATION.md#security-features)
## 📊 Documentation Statistics
| Document | Lines | Words | Topics Covered |
|----------|-------|-------|----------------|
| README.md | 268 | ~2,000 | Overview, Quick Start |
| QUICK_START.md | 285 | ~2,100 | Setup, Troubleshooting |
| DOCUMENTATION.md | 1,485 | ~12,000 | Everything! |
| ARCHITECTURE.md | 327 | ~2,500 | System Design |
| steps.md | 211 | ~1,200 | Setup Details |
| **Total** | **2,576** | **~19,800** | **Complete Coverage** |
## 🎯 Suggested Reading Paths
### Path 1: "I want to try it quickly"
1. [README.md](./README.md) (5 min read)
2. [QUICK_START.md](./QUICK_START.md) (15 min setup)
3. Start using OpenLearnX!
### Path 2: "I want to understand the system"
1. [README.md](./README.md) (5 min)
2. [ARCHITECTURE.md](./ARCHITECTURE.md) (15 min)
3. [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture) (20 min)
4. [DOCUMENTATION.md - Core Features](./DOCUMENTATION.md#core-features) (30 min)
### Path 3: "I want to contribute code"
1. [QUICK_START.md](./QUICK_START.md) (setup first)
2. [DOCUMENTATION.md - Project Structure](./DOCUMENTATION.md#project-structure) (20 min)
3. [DOCUMENTATION.md - Technology Stack](./DOCUMENTATION.md#technology-stack) (15 min)
4. [DOCUMENTATION.md - Contributing](./DOCUMENTATION.md#contributing) (10 min)
5. Start coding!
### Path 4: "I want to deploy in production"
1. [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture) (20 min)
2. [DOCUMENTATION.md - Security](./DOCUMENTATION.md#security-features) (15 min)
3. [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment) (30 min)
4. [ARCHITECTURE.md - Deployment Architecture](./ARCHITECTURE.md) (15 min)
### Path 5: "I want to understand blockchain integration"
1. [DOCUMENTATION.md - Smart Contracts](./DOCUMENTATION.md#smart-contracts) (20 min)
2. [DOCUMENTATION.md - Certificate Service](./DOCUMENTATION.md#certificate-service) (15 min)
3. Review `backend/contracts/CertificateNFT.sol` (code)
## 🔍 Finding Specific Information
### How do I...?
**Setup & Installation:**
- Install Foundry → [QUICK_START.md - Step 1](./QUICK_START.md#step-1-install-foundry-2-minutes)
- Configure MetaMask → [QUICK_START.md - MetaMask Setup](./QUICK_START.md#-metamask-setup-2-minutes)
- Deploy smart contract → [QUICK_START.md - Step 4](./QUICK_START.md#step-4-backend-setup-5-minutes)
- Start the application → [QUICK_START.md - Step 5](./QUICK_START.md#step-5-frontend-setup-6-minutes)
**Development:**
- Understand the architecture → [ARCHITECTURE.md](./ARCHITECTURE.md)
- Access the API → [DOCUMENTATION.md - API Documentation](./DOCUMENTATION.md#api-documentation)
- Understand database structure → [DOCUMENTATION.md - Database Schema](./DOCUMENTATION.md#database-schema)
- Add new features → [DOCUMENTATION.md - Contributing](./DOCUMENTATION.md#contributing)
**Features:**
- Take adaptive quizzes → [DOCUMENTATION.md - Adaptive Learning](./DOCUMENTATION.md#adaptive-learning-system)
- Compile code → [DOCUMENTATION.md - Compiler Service](./DOCUMENTATION.md#compiler-service)
- Mint certificates → [DOCUMENTATION.md - Certificate Service](./DOCUMENTATION.md#certificate-service)
- View analytics → [DOCUMENTATION.md - Dashboard Service](./DOCUMENTATION.md#dashboard-service)
**Operations:**
- Deploy with Docker → [DOCUMENTATION.md - Docker Deployment](./DOCUMENTATION.md#docker-deployment)
- Configure for production → [DOCUMENTATION.md - Production Deployment](./DOCUMENTATION.md#production-deployment)
- Secure the application → [DOCUMENTATION.md - Security Features](./DOCUMENTATION.md#security-features)
## 💡 Tips for Using the Documentation
1. **Use Ctrl+F (Cmd+F)** to search within documents
2. **Follow the links** - documents reference each other
3. **Check the Table of Contents** in DOCUMENTATION.md for quick navigation
4. **Start with examples** in QUICK_START.md before diving deep
5. **Refer to ARCHITECTURE.md** when lost in implementation details
## 🆘 Still Need Help?
If you can't find what you're looking for:
1. **Search GitHub Issues**: [OpenLearnX Issues](https://github.com/th30d4y/OpenLearnX/issues)
2. **Check Discussions**: [OpenLearnX Discussions](https://github.com/th30d4y/OpenLearnX/discussions)
3. **Review Troubleshooting**: [QUICK_START.md - Troubleshooting](./QUICK_START.md#-troubleshooting)
## 📝 Documentation Version
- **Last Updated**: 2026-01-31
- **Documentation Version**: 1.0.0
- **Project Version**: Alpha 1.0.0
## 🎓 Learning Resources Referenced
OpenLearnX documentation references these external resources:
- **Foundry Book**: https://book.getfoundry.sh/
- **Solidity Docs**: https://docs.soliditylang.org/
- **Next.js Docs**: https://nextjs.org/docs
- **Flask Docs**: https://flask.palletsprojects.com/
- **MongoDB Docs**: https://docs.mongodb.com/
- **OpenZeppelin**: https://docs.openzeppelin.com/
---
**Happy Learning with OpenLearnX! 🚀**
Start your journey: [QUICK_START.md](./QUICK_START.md)
DOCUMENTATION.md
+1485
View File
File diff suppressed because it is too large Load Diff
QUICK_START.md
+285
View File
@@ -0,0 +1,285 @@
# OpenLearnX - Quick Start Guide
Get OpenLearnX running in 15 minutes! ⚡
## Prerequisites Checklist
Before starting, ensure you have:
- [ ] **Node.js 18+** - `node --version`
- [ ] **Python 3.10+** - `python3 --version`
- [ ] **MongoDB** - `mongosh --version`
- [ ] **Git** - `git --version`
- [ ] **MetaMask** - Browser extension installed
---
## 🚀 5-Step Setup
### Step 1: Install Foundry (2 minutes)
```bash
# Install Foundry (Ethereum toolkit)
curl -L https://foundry.paradigm.xyz | bash
# Reload your shell
source ~/.bashrc # or source ~/.zshrc for zsh
# Install the toolchain
foundryup
# Verify (should show version numbers)
forge --version
anvil --version
```
### Step 2: Clone & Setup (1 minute)
```bash
# Clone repository
git clone https://github.com/th30d4y/OpenLearnX.git
cd OpenLearnX
```
### Step 3: Start Blockchain (1 minute)
**Open Terminal 1:**
```bash
# Start local Ethereum node
anvil --fork-url https://eth.merkle.io
# Leave this running!
# Note: Copy one of the private keys shown for later
```
### Step 4: Backend Setup (5 minutes)
**Open Terminal 2:**
```bash
cd backend
# Create Python virtual environment
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Deploy smart contract
python3 scripts/deploy.py
# ⚠️ IMPORTANT: Copy the contract address from output!
# Create .env file
cat > .env << EOF
FLASK_ENV=development
SECRET_KEY=dev-secret-key-change-in-production
MONGODB_URI=mongodb://localhost:27017/openlearnx
WEB3_PROVIDER_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
JWT_SECRET_KEY=jwt-secret-key
EOF
# Update CONTRACT_ADDRESS in .env with your deployed address!
# Start backend
python3 main.py
# Should see: Running on http://127.0.0.1:5000
```
### Step 5: Frontend Setup (6 minutes)
**Open Terminal 3:**
```bash
cd frontend
# Install dependencies
pnpm install
# or: npm install
# Create environment file
cat > .env.local << EOF
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
EOF
# Update CONTRACT_ADDRESS with your deployed address!
# Start frontend
pnpm run dev
# or: npm run dev
# Should see: Local: http://localhost:3000
```
---
## 🦊 MetaMask Setup (2 minutes)
1. **Open MetaMask extension**
2. **Add Local Network**:
- Click network dropdown
- "Add Network" → "Add a network manually"
- **Network Name**: `Anvil Local`
- **RPC URL**: `http://127.0.0.1:8545`
- **Chain ID**: `31337`
- **Currency Symbol**: `ETH`
- Click "Save"
3. **Import Test Account**:
- Click account icon → "Import Account"
- Paste private key from Anvil Terminal 1 (starts with 0xac...)
- Now you have 10000 test ETH!
---
## ✅ Test Your Setup
### 1. Open Browser
Navigate to: http://localhost:3000
### 2. Connect Wallet
- Click "Connect Wallet" button
- Select the imported account
- Approve connection
### 3. Test Backend API
```bash
# In a new terminal
curl http://127.0.0.1:5000/
# Should return: {"message": "OpenLearnX API is running"}
```
### 4. Take a Quiz
- Navigate to "Courses" or "Quizzes"
- Start an adaptive quiz
- Answer questions
- See instant feedback!
### 5. Mint a Certificate
- Complete a quiz with passing score
- Navigate to "Certificates"
- Click "Mint Certificate"
- Approve MetaMask transaction
- View your NFT certificate!
---
## 🐛 Troubleshooting
### Backend won't start
```bash
# Check MongoDB is running
sudo systemctl status mongodb
# or: mongosh
# Check Python version
python3 --version # Must be 3.10+
# Check virtual environment
which python # Should show venv path
```
### Frontend errors
```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```
### MetaMask connection fails
1. Check Anvil is running (Terminal 1)
2. Verify RPC URL is `http://127.0.0.1:8545`
3. Verify Chain ID is `31337`
4. Try switching networks back and forth
### Smart contract deployment fails
```bash
# Ensure Anvil is running
# Check you're in the backend directory
cd backend
source venv/bin/activate
python3 scripts/deploy.py
```
---
## 📚 Next Steps
Now that you're set up:
1. **Explore Features**:
- Try adaptive quizzes
- Write and run code in the compiler
- View your dashboard analytics
- Mint certificates
2. **Read Documentation**:
- [DOCUMENTATION.md](./DOCUMENTATION.md) - Comprehensive guide
- [steps.md](./steps.md) - Detailed setup instructions
3. **Customize**:
- Add your own courses (`backend/seed_courses.py`)
- Modify quiz questions
- Customize UI theme
4. **Contribute**:
- Report bugs
- Suggest features
- Submit pull requests
---
## 🎯 Common Commands Reference
### Start Development
```bash
# Terminal 1: Blockchain
anvil --fork-url https://eth.merkle.io
# Terminal 2: Backend
cd backend
source venv/bin/activate
python3 main.py
# Terminal 3: Frontend
cd frontend
pnpm run dev
```
### Stop Everything
```bash
# Stop Anvil: Ctrl+C in Terminal 1
# Stop Backend: Ctrl+C in Terminal 2
# Stop Frontend: Ctrl+C in Terminal 3
```
### Reset Database
```bash
cd backend
source venv/bin/activate
mongosh openlearnx --eval "db.dropDatabase()"
python3 seed_courses.py # Reseed data
```
### Redeploy Contract
```bash
cd backend
source venv/bin/activate
python3 scripts/deploy.py
# Update CONTRACT_ADDRESS in both .env files!
```
---
## 🆘 Getting Help
- 📖 **Full Documentation**: [DOCUMENTATION.md](./DOCUMENTATION.md)
- 🐛 **Issues**: [GitHub Issues](https://github.com/th30d4y/OpenLearnX/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/th30d4y/OpenLearnX/discussions)
---
**Happy Learning! 🎓**
README.md
+241 -17
View File
@@ -1,43 +1,267 @@
# OpenLearnX # OpenLearnX
**OpenLearnX** is a decentralized learning and assessment platform that blends adaptive testing, instant feedback, and blockchain-based certification. **OpenLearnX** is a cutting-edge decentralized learning and assessment platform that revolutionizes education through adaptive testing, instant feedback, and blockchain-based certification.
The goal is to give learners a smarter, personalized, and verifiable way to build and prove skills — from code challenges to real-world learning paths. The platform provides learners with a smarter, personalized, and verifiable way to build and prove skills — from code challenges to real-world learning paths, all backed by blockchain technology.
> 📚 **Documentation**: [DOCS_INDEX.md](./DOCS_INDEX.md) | [DOCUMENTATION.md](./DOCUMENTATION.md) | [QUICK_START.md](./QUICK_START.md)
--- ---
## ✨ What Makes It Different? ## ✨ What Makes It Different?
- **Adaptive Learning:** Challenges that scale with your skill level. - **🎯 Adaptive Learning:** Challenges that scale dynamically with your skill level using advanced algorithms
- **Instant Feedback:** Get results and explanations right away. - **⚡ Instant Feedback:** Get results and detailed explanations in real-time
- **Blockchain Certificates:** Earn NFTs as proof of learning. - **🔐 Blockchain Certificates:** Earn tamper-proof NFT certificates as verifiable proof of learning
- **Skill Dashboard:** Track progress over time, transparently. - **📊 Skill Dashboard:** Track progress over time with comprehensive analytics and competency mapping
- **Decentralized Storage:** Own your data, powered by IPFS. - **🌐 Decentralized Storage:** Own your data with IPFS-powered decentralized storage
- **💻 Multi-Language Compiler:** Execute code in 8+ programming languages with secure sandboxing
- **🤖 AI-Powered Quizzes:** Intelligent question generation and adaptive difficulty adjustment
- **👥 Peer Review System:** Collaborative learning with bias detection
--- ---
## 📌 Use Cases ## 📌 Use Cases
- Coding challenges with verified results (like LeetCode + web3) - **Coding Bootcamps:** Verify student progress with blockchain certificates
- Course completions with on-chain badges - **Professional Certification:** Issue tamper-proof credentials for completed courses
- Portfolios linked to wallet identity - **Corporate Training:** Track employee skill development with transparent analytics
- Verifiable skill progression - **Academic Assessments:** Adaptive testing that accurately measures student ability
- **Portfolio Building:** Showcase verified skills to potential employers
- **Skill Verification:** Employers can instantly verify candidate credentials on blockchain
---
## 🏗 Architecture Overview
```
Frontend (Next.js + React) → Backend (Flask + Python) → MongoDB Database
↓
Web3 Layer (Ethereum)
↓
Smart Contracts (Solidity) → IPFS Storage
```
**Key Components:**
- **Frontend**: Next.js 14, TypeScript, TailwindCSS, MetaMask integration
- **Backend**: Flask, TensorFlow, Web3.py, JWT authentication
- **Blockchain**: Solidity smart contracts, ERC-721 NFTs, Foundry toolkit
- **Database**: MongoDB, Redis cache
- **Storage**: IPFS for decentralized metadata
---
## 🚀 Quick Start
### Prerequisites
- Node.js 18+
- Python 3.10+
- MongoDB 6.0+
- Docker (optional)
- MetaMask browser extension
### Installation
1. **Install Foundry** (Blockchain toolkit):
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```
2. **Clone the repository**:
```bash
git clone https://github.com/th30d4y/OpenLearnX.git
cd OpenLearnX
```
3. **Start local blockchain** (Terminal 1):
```bash
anvil --fork-url https://eth.merkle.io
```
4. **Setup and start backend** (Terminal 2):
```bash
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Deploy smart contract
python3 scripts/deploy.py
# Start backend server
python3 main.py
```
5. **Setup and start frontend** (Terminal 3):
```bash
cd frontend
pnpm install
pnpm run dev
```
6. **Access the application**:
- Open http://localhost:3000
- Connect MetaMask wallet
- Start learning!
> 📖 **For detailed setup instructions, see [DOCUMENTATION.md](./DOCUMENTATION.md#setup--installation)**
--- ---
## 🌱 Project Status ## 🌱 Project Status
This is an early-stage open-source project under active development. **Current Version**: Alpha 1.0.0
Join us, fork it, or suggest features — contributions are welcome! **Status**: 🟢 Active Development
This is an open-source project under active development. Core features are functional, with continuous improvements being made.
### Recent Updates
- ✅ NFT certificate minting system
- ✅ Adaptive quiz algorithm
- ✅ Multi-language code compiler
- ✅ Comprehensive dashboard analytics
- ✅ Wallet-based authentication
### Roadmap
- 🔄 AI question generation refinement
- 🔄 Peer review system enhancements
- 📅 Mobile app (React Native)
- 📅 Live proctoring for exams
- 📅 Marketplace for courses
--- ---
## 🧪 Built With ## 🧪 Built With
- Solidity, Foundry, Anvil ### Frontend
- React, Wagmi, TailwindCSS - **Next.js 14** - React framework
- IPFS / Web3.Storage - **TypeScript** - Type safety
- MetaMask wallet integration - **TailwindCSS** - Styling
- **shadcn/ui** - Component library
- **ethers.js** - Ethereum interaction
- **MetaMask SDK** - Wallet integration
### Backend
- **Flask** - Python web framework
- **TensorFlow** - Machine learning
- **MongoDB** - Database
- **Redis** - Caching
- **Web3.py** - Blockchain interaction
- **Flask-JWT-Extended** - Authentication
### Blockchain
- **Solidity 0.8.19** - Smart contracts
- **Foundry** - Development toolkit
- **OpenZeppelin** - Secure contract libraries
- **IPFS** - Decentralized storage
- **Anvil** - Local Ethereum node
---
## 📊 Key Features
### For Students
- 🎓 Personalized adaptive learning paths
- 💯 Instant feedback on assessments
- 🏆 Blockchain-verified certificates (NFTs)
- 📈 Progress tracking and analytics
- 💻 Interactive coding challenges
- 🌟 Skill competency mapping
### For Instructors
- 📚 Course creation and management
- 👥 Student progress monitoring
- 📊 Comprehensive analytics dashboard
- ✍️ Quiz and assessment authoring
- 🔍 Bias detection in grading
- 📝 Automated and manual grading
### For Employers
- ✅ Instant credential verification
- 🔗 Blockchain-backed authenticity
- 📋 Detailed skill assessments
- 🎯 Candidate skill mapping
- 🔍 Transparent learning history
---
## 📚 Documentation
Comprehensive documentation is available in [DOCUMENTATION.md](./DOCUMENTATION.md), including:
- 📖 Detailed architecture explanation
- 🔧 Technology stack deep dive
- 📁 Project structure overview
- 📜 Smart contract documentation
- 🖥️ Backend services guide
- 🎨 Frontend components reference
- 💾 Database schema
- 🔌 API documentation
- ⚙️ Advanced configuration
- 🚀 Production deployment guide
- 🔒 Security best practices
---
## 🤝 Contributing
We welcome contributions from the community! Whether it's:
- 🐛 Bug reports and fixes
- ✨ New features
- 📚 Documentation improvements
- 🌐 Translations
- 🎨 UI/UX enhancements
- 🧪 Test coverage
**How to contribute:**
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Please read [DOCUMENTATION.md](./DOCUMENTATION.md#contributing) for detailed contribution guidelines.
---
## 📄 License
[Include your license here - e.g., MIT License]
---
## 🙏 Acknowledgments
- **OpenZeppelin** - Secure smart contract libraries
- **Foundry** - Ethereum development toolkit
- **Next.js Team** - Amazing React framework
- **TensorFlow** - Machine learning framework
- **All Contributors** - Thank you for making OpenLearnX better!
---
## 📞 Contact & Support
- 🌐 Website: [your-website.com]
- 💬 Discord: [your-discord-link]
- 🐦 Twitter: [@OpenLearnX]
- 📧 Email: [your-email]
- 📖 Docs: [DOCUMENTATION.md](./DOCUMENTATION.md)
---
## ⭐ Show Your Support
If you find OpenLearnX useful, please consider:
- ⭐ Starring this repository
- 🔄 Sharing with others
- 🐛 Reporting bugs
- ✨ Contributing code
- 💬 Joining our community
**Together, let's revolutionize education! 🚀**
--- ---