0x5t4l1n/OpenLearnX
1
0
Fork 0
mirror of https://github.com/th30d4y/OpenLearnX.git synced 2026-05-26 11:25:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add quick start guide and architecture documentation

Browse Source 
Co-authored-by: Stalin-143 <161853795+Stalin-143@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-01-31 16:41:27 +00:00
parent d0deff302c
commit e057ba3aea
2 changed files with 612 additions and 0 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)
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! 🎓**