OpenLearnX/dev.md

OpenLearnX Development Guide

Last Updated: May 12, 2026
Status: All services operational

---

🚀 Quick Start (5 minutes)

Prerequisites

• Node.js 18+
• Python 3.10+
• MongoDB 4.4+
• Foundry (Anvil)

One-Command Setup

# Terminal 1: Start MongoDB
mongod --dbpath ~/mongodata

# Terminal 2: Start Anvil blockchain
export PATH="/home/w4nn4d13/.foundry/bin:$PATH"
anvil

# Terminal 3: Start Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r ../requirements.txt
python3 main.py

# Terminal 4: Start Frontend
cd frontend
pnpm install
pnpm dev

---

📋 Complete Setup Guide

Step 1: MongoDB Setup

# Start MongoDB (local development)
mongod --dbpath ~/mongodata --logpath /tmp/mongodb.log

# Verify connection
mongosh
> use openlearnx
> db.stats()

Step 2: Blockchain Setup

# Install Foundry (if not installed)
curl -L https://foundry.paradigm.xyz | bash
source ~/.bashrc  # or ~/.zshrc
foundryup

# Start Anvil local blockchain
export PATH="/home/w4nn4d13/.foundry/bin:$PATH"
anvil

# You'll see test accounts printed:
# Account 0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
# Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Step 3: Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r ../requirements.txt

# 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
DEPLOYER_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
JWT_SECRET_KEY=jwt-secret-key
CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
EOF

# Deploy smart contract
python3 scripts/deploy.py

# Start backend
python3 main.py
# Should see: Running on http://127.0.0.1:5000

Step 4: Frontend Setup

cd frontend

# Install dependencies
pnpm install

# Create .env.local
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

# Start development server
pnpm dev
# Should see: Local: http://localhost:3000

---

📊 Services Overview

Available Services

Service	Port	URL	Status
MongoDB	27017	localhost:27017	Database
Anvil	8545	http://127.0.0.1:8545	Blockchain
Backend	5000	http://localhost:5000	Flask API
Frontend	3000	http://localhost:3000	Next.js UI

Service Status Check

# Check all services
echo "MongoDB:" && pgrep mongod >/dev/null && echo "✅ Running" || echo "❌ Stopped"
echo "Anvil:" && pgrep anvil >/dev/null && echo "✅ Running" || echo "❌ Stopped"
echo "Backend:" && curl -s http://localhost:5000/api/health >/dev/null && echo "✅ Running" || echo "❌ Stopped"
echo "Frontend:" && curl -s http://localhost:3000 >/dev/null && echo "✅ Running" || echo "❌ Stopped"

---

🔧 Common Development Tasks

Backend Development

Run tests

cd backend
python3 -m pytest tests/ -v

Rebuild smart contracts

cd backend
export PATH="/home/w4nn4d13/.foundry/bin:$PATH"
forge build

Deploy contract to Anvil

cd backend
python3 scripts/deploy.py

View backend logs

tail -f /tmp/openlearnx_backend.log

API Health Check

curl http://localhost:5000/api/health

Frontend Development

Hot reload mode (automatic)

cd frontend
pnpm dev

Build for production

cd frontend
pnpm build

Build and start production build

cd frontend
pnpm build
pnpm start

Lint and format

cd frontend
pnpm lint
pnpm format

---

📝 Environment Variables

Backend (.env)

# Flask
FLASK_ENV=development
DEBUG=True
SECRET_KEY=dev-secret-key

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

# Blockchain
WEB3_PROVIDER_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
DEPLOYER_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# JWT
JWT_SECRET_KEY=jwt-secret-key

# Admin
ADMIN_TOKEN=admin-token-change-this

Frontend (.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

---

🧪 Testing

Backend Tests

cd backend
source venv/bin/activate
python3 -m pytest tests/ -v
python3 -m pytest tests/ -v --cov=  # With coverage

API Testing with curl

# Health check
curl http://localhost:5000/api/health

# Dashboard stats
curl http://localhost:5000/api/dashboard/comprehensive-stats

# List courses
curl http://localhost:5000/api/courses

# List quizzes
curl http://localhost:5000/api/quizzes

Frontend Testing

cd frontend
pnpm test           # Run tests
pnpm test:watch    # Watch mode

---

🔍 Debugging

Backend Debugging

Enable verbose logging

# In main.py
import logging
logging.basicConfig(level=logging.DEBUG)

Check database

mongosh
use openlearnx
db.users.find()
db.quizzes.find()

Check blockchain

# If Anvil is running, check accounts
curl -X POST http://127.0.0.1:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'

Frontend Debugging

Chrome DevTools

• Open http://localhost:3000
• Press F12 to open DevTools
• Check Console, Network, and Application tabs

Next.js Debug Mode

NODE_DEBUG_SKIP_TYPES=*-skip pnpm dev

---

📦 Dependency Management

Backend

Add Python package

cd backend
source venv/bin/activate
pip install package-name
pip freeze > ../requirements.txt

Update all dependencies

cd backend
source venv/bin/activate
pip install --upgrade pip
pip install -U -r ../requirements.txt

Frontend

Add npm package

cd frontend
pnpm add package-name

Add dev dependency

cd frontend
pnpm add -D package-name

Update packages

cd frontend
pnpm update

---

🛑 Stop Services

Stop Individual Services

# Backend
pkill -f "python3.*main.py"

# Frontend
pkill -f "next dev"

# Anvil
pkill anvil

# MongoDB
killall mongod

Stop All Services

pkill mongod && pkill anvil && pkill -f "python3.*main.py" && pkill -f "next dev"

---

🐛 Troubleshooting

MongoDB Connection Error

# Kill any stuck processes
killall mongod

# Remove lock file
rm -f ~/mongodata/mongod.lock

# Restart MongoDB
mongod --dbpath ~/mongodata

Port Already in Use

# Find process using port
lsof -i :5000    # Backend
lsof -i :3000    # Frontend
lsof -i :8545    # Anvil
lsof -i :27017   # MongoDB

# Kill process
kill -9 <PID>

Backend Won't Start

cd backend
source venv/bin/activate

# Reinstall dependencies
pip install -r ../requirements.txt

# Check Python version
python3 --version  # Should be 3.10+

# Try running with more verbose output
python3 main.py -v

Frontend Won't Build

cd frontend

# Clear cache
rm -rf .next node_modules pnpm-lock.yaml

# Reinstall
pnpm install

# Try building again
pnpm build

Anvil Issues

# Check if Foundry is installed correctly
forge --version
anvil --version

# Reinstall Foundry
curl -L https://foundry.paradigm.xyz | bash
source ~/.bashrc
foundryup

---

📚 Useful Resources

• Backend Framework: Flask - https://flask.palletsprojects.com/
• Frontend Framework: Next.js - https://nextjs.org/
• Database: MongoDB - https://www.mongodb.com/
• Blockchain: Foundry - https://book.getfoundry.sh/
• API Testing: Postman - https://www.postman.com/

---

🚀 Deployment

For production deployment, see:

• PRODUCTION_DEPLOYMENT.md
• DEPLOYMENT_GUIDE.md

---

📞 Getting Help

Check Logs

# Backend logs
tail -f /tmp/mongodb.log
pm2 logs openlearnx-backend

# Frontend logs
pm2 logs openlearnx-frontend

View Git History

git log --oneline -10
git diff HEAD~1

Report Issues

1. Check GitHub Issues
2. Create new issue with:
   • Description of problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment (OS, versions, etc.)

---

✅ Development Checklist

• MongoDB running
• Anvil running
• Backend running (http://localhost:5000)
• Frontend running (http://localhost:3000)
• Can connect to MetaMask
• Can create account
• Can browse courses
• Can take quiz
• Can mint certificate
• Database has test data

---

🎯 Next Steps

1. Understand Architecture: Read ARCHITECTURE.md
2. Explore API: Check Backend Routes
3. Explore Components: Check Frontend Components
4. Review Smart Contracts: Check Contracts
5. Read Tests: Check Test Files and Frontend Tests

---

Happy developing! 🎉