From e057ba3aea1ae76fa78ed5f0adaf0e271bc387ae Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 31 Jan 2026 16:41:27 +0000 Subject: [PATCH] Add quick start guide and architecture documentation Co-authored-by: Stalin-143 <161853795+Stalin-143@users.noreply.github.com> --- ARCHITECTURE.md | 327 ++++++++++++++++++++++++++++++++++++++++++++++++ QUICK_START.md | 285 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 612 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 QUICK_START.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..f189c17 --- /dev/null +++ b/ARCHITECTURE.md @@ -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) diff --git a/QUICK_START.md b/QUICK_START.md new file mode 100644 index 0000000..de6c6df --- /dev/null +++ b/QUICK_START.md @@ -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! 🎓**