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

Add development guide (dev.md)

Browse Source 
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
2026-05-12 20:06:18 +05:30
parent 1412ccf58c
commit ea05201167
1 changed files with 526 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev.md
+526
View File
@@ -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! 🎉**