mirror of
https://github.com/th30d4y/OpenLearnX.git
synced 2026-05-26 19:26:33 +00:00
Add quick start guide and architecture documentation
Co-authored-by: Stalin-143 <161853795+Stalin-143@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
+285
@@ -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! 🎓**
|
||||
Reference in New Issue
Block a user