mirror of
https://github.com/th30d4y/OpenLearnX.git
synced 2026-05-26 19:26:33 +00:00
Add development guide (dev.md)
Comprehensive development documentation including: - Quick start guide (5 minutes setup) - Complete setup instructions for all services - MongoDB, Anvil, Backend, and Frontend setup - Service overview and status checks - Common development tasks - Environment variable configuration - Testing guidelines - Debugging tips - Dependency management - Troubleshooting guide - Development checklist This file helps new developers get started quickly with the project.
This commit is contained in:
Stalin
@@ -0,0 +1,526 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Start MongoDB (local development)
|
||||
mongod --dbpath ~/mongodata --logpath /tmp/mongodb.log
|
||||
|
||||
# Verify connection
|
||||
mongosh
|
||||
> use openlearnx
|
||||
> db.stats()
|
||||
```
|
||||
|
||||
### Step 2: Blockchain Setup
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
cd backend
|
||||
python3 -m pytest tests/ -v
|
||||
```
|
||||
|
||||
#### Rebuild smart contracts
|
||||
```bash
|
||||
cd backend
|
||||
export PATH="/home/w4nn4d13/.foundry/bin:$PATH"
|
||||
forge build
|
||||
```
|
||||
|
||||
#### Deploy contract to Anvil
|
||||
```bash
|
||||
cd backend
|
||||
python3 scripts/deploy.py
|
||||
```
|
||||
|
||||
#### View backend logs
|
||||
```bash
|
||||
tail -f /tmp/openlearnx_backend.log
|
||||
```
|
||||
|
||||
#### API Health Check
|
||||
```bash
|
||||
curl http://localhost:5000/api/health
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
#### Hot reload mode (automatic)
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
#### Build for production
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm build
|
||||
```
|
||||
|
||||
#### Build and start production build
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm build
|
||||
pnpm start
|
||||
```
|
||||
|
||||
#### Lint and format
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm lint
|
||||
pnpm format
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Environment Variables
|
||||
|
||||
### Backend (.env)
|
||||
```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)
|
||||
```env
|
||||
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
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
python3 -m pytest tests/ -v
|
||||
python3 -m pytest tests/ -v --cov= # With coverage
|
||||
```
|
||||
|
||||
### API Testing with curl
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm test # Run tests
|
||||
pnpm test:watch # Watch mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Debugging
|
||||
|
||||
### Backend Debugging
|
||||
|
||||
#### Enable verbose logging
|
||||
```python
|
||||
# In main.py
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
```
|
||||
|
||||
#### Check database
|
||||
```bash
|
||||
mongosh
|
||||
use openlearnx
|
||||
db.users.find()
|
||||
db.quizzes.find()
|
||||
```
|
||||
|
||||
#### Check blockchain
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
NODE_DEBUG_SKIP_TYPES=*-skip pnpm dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Dependency Management
|
||||
|
||||
### Backend
|
||||
|
||||
#### Add Python package
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
pip install package-name
|
||||
pip freeze > ../requirements.txt
|
||||
```
|
||||
|
||||
#### Update all dependencies
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
pip install --upgrade pip
|
||||
pip install -U -r ../requirements.txt
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
#### Add npm package
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm add package-name
|
||||
```
|
||||
|
||||
#### Add dev dependency
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm add -D package-name
|
||||
```
|
||||
|
||||
#### Update packages
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 Stop Services
|
||||
|
||||
### Stop Individual Services
|
||||
```bash
|
||||
# Backend
|
||||
pkill -f "python3.*main.py"
|
||||
|
||||
# Frontend
|
||||
pkill -f "next dev"
|
||||
|
||||
# Anvil
|
||||
pkill anvil
|
||||
|
||||
# MongoDB
|
||||
killall mongod
|
||||
```
|
||||
|
||||
### Stop All Services
|
||||
```bash
|
||||
pkill mongod && pkill anvil && pkill -f "python3.*main.py" && pkill -f "next dev"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### MongoDB Connection Error
|
||||
```bash
|
||||
# Kill any stuck processes
|
||||
killall mongod
|
||||
|
||||
# Remove lock file
|
||||
rm -f ~/mongodata/mongod.lock
|
||||
|
||||
# Restart MongoDB
|
||||
mongod --dbpath ~/mongodata
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Clear cache
|
||||
rm -rf .next node_modules pnpm-lock.yaml
|
||||
|
||||
# Reinstall
|
||||
pnpm install
|
||||
|
||||
# Try building again
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### Anvil Issues
|
||||
```bash
|
||||
# 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](./PRODUCTION_DEPLOYMENT.md)
|
||||
- [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
### Check Logs
|
||||
```bash
|
||||
# Backend logs
|
||||
tail -f /tmp/mongodb.log
|
||||
pm2 logs openlearnx-backend
|
||||
|
||||
# Frontend logs
|
||||
pm2 logs openlearnx-frontend
|
||||
```
|
||||
|
||||
### View Git History
|
||||
```bash
|
||||
git log --oneline -10
|
||||
git diff HEAD~1
|
||||
```
|
||||
|
||||
### Report Issues
|
||||
1. Check [GitHub Issues](https://github.com/th30d4y/OpenLearnX/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](./ARCHITECTURE.md)
|
||||
2. **Explore API**: Check [Backend Routes](./backend/routes/)
|
||||
3. **Explore Components**: Check [Frontend Components](./frontend/components/)
|
||||
4. **Review Smart Contracts**: Check [Contracts](./backend/contracts/)
|
||||
5. **Read Tests**: Check [Test Files](./backend/tests/) and [Frontend Tests](./frontend/__tests__/)
|
||||
|
||||
---
|
||||
|
||||
**Happy developing! 🎉**
|
||||
Reference in New Issue
Block a user