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/DOCS_INDEX.md b/DOCS_INDEX.md
new file mode 100644
index 0000000..e6aeda7
--- /dev/null
+++ b/DOCS_INDEX.md
@@ -0,0 +1,223 @@
+# 📖 OpenLearnX Documentation Index
+
+Welcome to OpenLearnX! This index will help you navigate all the documentation.
+
+## 🚀 Getting Started
+
+**New to OpenLearnX?** Start here:
+
+1. **[README.md](./README.md)** ⭐ START HERE
+   - Project overview
+   - Quick feature highlights
+   - Brief setup instructions
+   - Community links
+
+2. **[QUICK_START.md](./QUICK_START.md)** ⚡ 15-MINUTE SETUP
+   - Step-by-step installation guide
+   - MetaMask configuration
+   - Testing your setup
+   - Troubleshooting common issues
+
+## 📚 Deep Dive Documentation
+
+**Ready to learn more?** Explore these comprehensive guides:
+
+3. **[DOCUMENTATION.md](./DOCUMENTATION.md)** 📖 COMPLETE GUIDE
+   - Comprehensive project documentation (1,485 lines!)
+   - Detailed architecture explanation
+   - Technology stack deep dive
+   - API documentation
+   - Security features
+   - Production deployment guide
+   - Contributing guidelines
+   
+   **Sections include:**
+   - Project Overview & Vision
+   - Core Features (8 major features)
+   - Architecture & Design
+   - Technology Stack Details
+   - Project Structure Walkthrough
+   - Smart Contract Documentation
+   - Backend Services Guide
+   - Frontend Application Guide
+   - Database Schema
+   - Complete API Reference
+   - Setup & Installation
+   - Deployment Strategies
+   - Security Features
+   - Contributing Guidelines
+
+4. **[ARCHITECTURE.md](./ARCHITECTURE.md)** 🏗️ SYSTEM DESIGN
+   - Visual architecture diagrams
+   - Component interaction flows
+   - Data flow diagrams
+   - Technology stack maps
+   - Security architecture
+   - Deployment architecture
+
+5. **[steps.md](./steps.md)** 🔧 DETAILED SETUP
+   - Original setup guide
+   - Terminal-by-terminal instructions
+   - Database configuration
+   - Frontend project structure
+
+## 📋 Documentation Quick Reference
+
+### By Audience
+
+#### For Developers
+- Start: [QUICK_START.md](./QUICK_START.md)
+- Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+- API Reference: [DOCUMENTATION.md](./DOCUMENTATION.md#api-documentation)
+- Contributing: [DOCUMENTATION.md](./DOCUMENTATION.md#contributing)
+
+#### For Students/Users
+- Overview: [README.md](./README.md)
+- Getting Started: [QUICK_START.md](./QUICK_START.md)
+- Features: [DOCUMENTATION.md](./DOCUMENTATION.md#core-features)
+
+#### For Instructors
+- Dashboard Guide: [DOCUMENTATION.md](./DOCUMENTATION.md#comprehensive-dashboard)
+- Course Creation: [DOCUMENTATION.md](./DOCUMENTATION.md#backend-services)
+- Analytics: [DOCUMENTATION.md](./DOCUMENTATION.md#dashboard-service)
+
+#### For DevOps/SysAdmins
+- Deployment: [DOCUMENTATION.md](./DOCUMENTATION.md#deployment)
+- Docker Setup: [DOCUMENTATION.md](./DOCUMENTATION.md#docker-deployment)
+- Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+- Security: [DOCUMENTATION.md](./DOCUMENTATION.md#security-features)
+
+### By Topic
+
+#### Setup & Installation
+- Quick (15 min): [QUICK_START.md](./QUICK_START.md)
+- Detailed: [steps.md](./steps.md)
+- Production: [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment)
+
+#### Architecture & Design
+- Overview: [ARCHITECTURE.md](./ARCHITECTURE.md)
+- System Design: [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture)
+- Components: [DOCUMENTATION.md - Project Structure](./DOCUMENTATION.md#project-structure)
+
+#### Features & Capabilities
+- Feature List: [README.md - Core Features](./README.md#core-features)
+- Detailed Features: [DOCUMENTATION.md - Core Features](./DOCUMENTATION.md#core-features)
+- Use Cases: [README.md - Use Cases](./README.md#use-cases)
+
+#### Development
+- Tech Stack: [DOCUMENTATION.md - Technology Stack](./DOCUMENTATION.md#technology-stack)
+- API Docs: [DOCUMENTATION.md - API Documentation](./DOCUMENTATION.md#api-documentation)
+- Database: [DOCUMENTATION.md - Database Schema](./DOCUMENTATION.md#database-schema)
+- Smart Contracts: [DOCUMENTATION.md - Smart Contracts](./DOCUMENTATION.md#smart-contracts)
+
+#### Operations
+- Deployment: [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment)
+- Docker: [DOCUMENTATION.md - Docker Deployment](./DOCUMENTATION.md#docker-deployment)
+- Security: [DOCUMENTATION.md - Security Features](./DOCUMENTATION.md#security-features)
+
+## 📊 Documentation Statistics
+
+| Document | Lines | Words | Topics Covered |
+|----------|-------|-------|----------------|
+| README.md | 268 | ~2,000 | Overview, Quick Start |
+| QUICK_START.md | 285 | ~2,100 | Setup, Troubleshooting |
+| DOCUMENTATION.md | 1,485 | ~12,000 | Everything! |
+| ARCHITECTURE.md | 327 | ~2,500 | System Design |
+| steps.md | 211 | ~1,200 | Setup Details |
+| **Total** | **2,576** | **~19,800** | **Complete Coverage** |
+
+## 🎯 Suggested Reading Paths
+
+### Path 1: "I want to try it quickly" 
+1. [README.md](./README.md) (5 min read)
+2. [QUICK_START.md](./QUICK_START.md) (15 min setup)
+3. Start using OpenLearnX!
+
+### Path 2: "I want to understand the system"
+1. [README.md](./README.md) (5 min)
+2. [ARCHITECTURE.md](./ARCHITECTURE.md) (15 min)
+3. [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture) (20 min)
+4. [DOCUMENTATION.md - Core Features](./DOCUMENTATION.md#core-features) (30 min)
+
+### Path 3: "I want to contribute code"
+1. [QUICK_START.md](./QUICK_START.md) (setup first)
+2. [DOCUMENTATION.md - Project Structure](./DOCUMENTATION.md#project-structure) (20 min)
+3. [DOCUMENTATION.md - Technology Stack](./DOCUMENTATION.md#technology-stack) (15 min)
+4. [DOCUMENTATION.md - Contributing](./DOCUMENTATION.md#contributing) (10 min)
+5. Start coding!
+
+### Path 4: "I want to deploy in production"
+1. [DOCUMENTATION.md - Architecture](./DOCUMENTATION.md#architecture) (20 min)
+2. [DOCUMENTATION.md - Security](./DOCUMENTATION.md#security-features) (15 min)
+3. [DOCUMENTATION.md - Deployment](./DOCUMENTATION.md#deployment) (30 min)
+4. [ARCHITECTURE.md - Deployment Architecture](./ARCHITECTURE.md) (15 min)
+
+### Path 5: "I want to understand blockchain integration"
+1. [DOCUMENTATION.md - Smart Contracts](./DOCUMENTATION.md#smart-contracts) (20 min)
+2. [DOCUMENTATION.md - Certificate Service](./DOCUMENTATION.md#certificate-service) (15 min)
+3. Review `backend/contracts/CertificateNFT.sol` (code)
+
+## 🔍 Finding Specific Information
+
+### How do I...?
+
+**Setup & Installation:**
+- Install Foundry → [QUICK_START.md - Step 1](./QUICK_START.md#step-1-install-foundry-2-minutes)
+- Configure MetaMask → [QUICK_START.md - MetaMask Setup](./QUICK_START.md#-metamask-setup-2-minutes)
+- Deploy smart contract → [QUICK_START.md - Step 4](./QUICK_START.md#step-4-backend-setup-5-minutes)
+- Start the application → [QUICK_START.md - Step 5](./QUICK_START.md#step-5-frontend-setup-6-minutes)
+
+**Development:**
+- Understand the architecture → [ARCHITECTURE.md](./ARCHITECTURE.md)
+- Access the API → [DOCUMENTATION.md - API Documentation](./DOCUMENTATION.md#api-documentation)
+- Understand database structure → [DOCUMENTATION.md - Database Schema](./DOCUMENTATION.md#database-schema)
+- Add new features → [DOCUMENTATION.md - Contributing](./DOCUMENTATION.md#contributing)
+
+**Features:**
+- Take adaptive quizzes → [DOCUMENTATION.md - Adaptive Learning](./DOCUMENTATION.md#adaptive-learning-system)
+- Compile code → [DOCUMENTATION.md - Compiler Service](./DOCUMENTATION.md#compiler-service)
+- Mint certificates → [DOCUMENTATION.md - Certificate Service](./DOCUMENTATION.md#certificate-service)
+- View analytics → [DOCUMENTATION.md - Dashboard Service](./DOCUMENTATION.md#dashboard-service)
+
+**Operations:**
+- Deploy with Docker → [DOCUMENTATION.md - Docker Deployment](./DOCUMENTATION.md#docker-deployment)
+- Configure for production → [DOCUMENTATION.md - Production Deployment](./DOCUMENTATION.md#production-deployment)
+- Secure the application → [DOCUMENTATION.md - Security Features](./DOCUMENTATION.md#security-features)
+
+## 💡 Tips for Using the Documentation
+
+1. **Use Ctrl+F (Cmd+F)** to search within documents
+2. **Follow the links** - documents reference each other
+3. **Check the Table of Contents** in DOCUMENTATION.md for quick navigation
+4. **Start with examples** in QUICK_START.md before diving deep
+5. **Refer to ARCHITECTURE.md** when lost in implementation details
+
+## 🆘 Still Need Help?
+
+If you can't find what you're looking for:
+
+1. **Search GitHub Issues**: [OpenLearnX Issues](https://github.com/th30d4y/OpenLearnX/issues)
+2. **Check Discussions**: [OpenLearnX Discussions](https://github.com/th30d4y/OpenLearnX/discussions)
+3. **Review Troubleshooting**: [QUICK_START.md - Troubleshooting](./QUICK_START.md#-troubleshooting)
+
+## 📝 Documentation Version
+
+- **Last Updated**: 2026-01-31
+- **Documentation Version**: 1.0.0
+- **Project Version**: Alpha 1.0.0
+
+## 🎓 Learning Resources Referenced
+
+OpenLearnX documentation references these external resources:
+- **Foundry Book**: https://book.getfoundry.sh/
+- **Solidity Docs**: https://docs.soliditylang.org/
+- **Next.js Docs**: https://nextjs.org/docs
+- **Flask Docs**: https://flask.palletsprojects.com/
+- **MongoDB Docs**: https://docs.mongodb.com/
+- **OpenZeppelin**: https://docs.openzeppelin.com/
+
+---
+
+**Happy Learning with OpenLearnX! 🚀**
+
+Start your journey: [QUICK_START.md](./QUICK_START.md)
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
new file mode 100644
index 0000000..723b176
--- /dev/null
+++ b/DOCUMENTATION.md
@@ -0,0 +1,1485 @@
+# OpenLearnX - Comprehensive Project Documentation
+
+## 📋 Table of Contents
+1. [Project Overview](#project-overview)
+2. [Core Features](#core-features)
+3. [Architecture](#architecture)
+4. [Technology Stack](#technology-stack)
+5. [Project Structure](#project-structure)
+6. [Smart Contracts](#smart-contracts)
+7. [Backend Services](#backend-services)
+8. [Frontend Application](#frontend-application)
+9. [Database Schema](#database-schema)
+10. [API Documentation](#api-documentation)
+11. [Setup & Installation](#setup--installation)
+12. [Deployment](#deployment)
+13. [Security Features](#security-features)
+14. [Contributing](#contributing)
+
+---
+
+## 🎯 Project Overview
+
+**OpenLearnX** is a cutting-edge, decentralized learning and assessment platform that revolutionizes how learners acquire, demonstrate, and verify their skills. Built on Web3 technologies, it combines adaptive learning algorithms, real-time feedback systems, and blockchain-based certification to create a transparent, verifiable, and personalized educational experience.
+
+### Vision
+To democratize education by providing learners with:
+- Personalized, adaptive learning experiences that scale with their skill level
+- Instant, actionable feedback on their performance
+- Immutable, blockchain-verified certificates that employers can trust
+- Full ownership of their learning data through decentralized storage
+
+### Problem It Solves
+1. **Traditional Credentials Are Unverifiable**: Paper certificates and digital badges can be forged
+2. **One-Size-Fits-All Learning**: Static courses don't adapt to individual learner needs
+3. **Delayed Feedback**: Students wait days or weeks for assessment results
+4. **Data Ownership**: Learners don't control their educational records
+5. **Skill Verification**: Employers struggle to verify claimed skills
+
+---
+
+## ✨ Core Features
+
+### 1. Adaptive Learning System
+- **Dynamic Difficulty Adjustment**: Questions adapt in real-time based on learner performance
+- **Personalized Learning Paths**: AI-driven recommendation engine suggests optimal learning sequences
+- **Skill Gap Analysis**: Identifies weaknesses and focuses learning where it's needed most
+- **Progressive Difficulty Curve**: Gradually increases challenge as competency improves
+
+### 2. Instant Feedback & Assessment
+- **Real-Time Code Execution**: Run and test code in multiple programming languages
+- **Immediate Results**: Get instant feedback on quiz answers and code submissions
+- **Detailed Explanations**: Understand why answers are correct or incorrect
+- **Performance Analytics**: Track progress over time with comprehensive metrics
+
+### 3. Blockchain Certificates (NFT)
+- **ERC-721 NFT Certificates**: Each certificate is a unique, non-transferable NFT
+- **On-Chain Verification**: Anyone can verify certificate authenticity on the blockchain
+- **IPFS Metadata Storage**: Certificate details stored on decentralized storage
+- **Permanent Record**: Certificates cannot be revoked or altered once minted
+- **Wallet Integration**: MetaMask wallet connects learners to their certificates
+
+### 4. Comprehensive Dashboard
+- **Student Dashboard**: 
+  - Progress tracking across multiple subjects
+  - Competency radar charts showing skill distribution
+  - Certificate gallery with blockchain verification
+  - Learning history and timeline
+- **Instructor Dashboard**:
+  - Class performance analytics
+  - Student progress monitoring
+  - Assessment creation and management
+  - Bias detection in grading
+
+### 5. Multi-Language Code Compiler
+- **Supported Languages**: Python, JavaScript, Java, C++, C, Go, Rust, and more
+- **Secure Execution**: Sandboxed environment with resource limits
+- **Real-Time Output**: See compilation errors and execution results instantly
+- **Test Cases**: Automated testing against predefined test cases
+
+### 6. AI-Powered Quiz Generation
+- **LLM Integration**: Uses machine learning to generate contextual questions
+- **Adaptive Question Selection**: Picks questions based on difficulty and topic
+- **Auto-Grading**: Automated evaluation of multiple-choice and coding questions
+- **Question Banking**: Extensive library of pre-validated questions
+
+### 7. Peer Review System
+- **Collaborative Learning**: Students review each other's work
+- **Bias Detection**: AI monitors for grading bias and inconsistencies
+- **Portfolio Building**: Showcase best work for potential employers
+- **Anonymous Reviews**: Optional anonymity to reduce bias
+
+### 8. Decentralized Chat
+- **Peer-to-Peer Communication**: Built on blockchain smart contracts
+- **Study Groups**: Create topic-based discussion channels
+- **Encrypted Messages**: Private, secure communication
+- **Persistent History**: Chat logs stored on-chain
+
+---
+
+## 🏗 Architecture
+
+OpenLearnX follows a modern **microservices architecture** with clear separation of concerns:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Frontend Layer                           │
+│  (Next.js 14 + React + TypeScript + TailwindCSS)               │
+│  - User Interface                                               │
+│  - Wallet Integration (MetaMask)                                │
+│  - Real-time Updates                                            │
+└────────────────────────┬───────────────────────────────────────┘
+                         │ HTTPS/WebSocket
+┌────────────────────────┴───────────────────────────────────────┐
+│                      Backend Layer (Flask)                      │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
+│  │ Auth Service │  │ Quiz Service │  │ Cert Service │        │
+│  └──────────────┘  └──────────────┘  └──────────────┘        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
+│  │ Compiler Svc │  │ Dashboard Svc│  │ Adaptive AI  │        │
+│  └──────────────┘  └──────────────┘  └──────────────┘        │
+└────────────────────────┬───────────────────────────────────────┘
+                         │
+         ┌───────────────┼───────────────┐
+         │               │               │
+┌────────┴─────┐ ┌──────┴──────┐ ┌─────┴──────────┐
+│   MongoDB    │ │  PostgreSQL │ │  Redis Cache   │
+│  (Primary DB)│ │   (Future)  │ │  (Sessions)    │
+└──────────────┘ └─────────────┘ └────────────────┘
+         │
+         │
+┌────────┴─────────────────────────────────────────────┐
+│           Blockchain Layer (Ethereum/Anvil)          │
+│  ┌──────────────────────────────────────────┐        │
+│  │  CertificateNFT Smart Contract (Solidity)│        │
+│  │  - Mint NFT certificates                 │        │
+│  │  - Verify authenticity                   │        │
+│  │  - Track ownership                       │        │
+│  └──────────────────────────────────────────┘        │
+└──────────────────────────────────────────────────────┘
+         │
+┌────────┴─────┐
+│     IPFS     │  (Decentralized Storage)
+│  Metadata    │  - Certificate details
+│   Storage    │  - Learning records
+└──────────────┘
+```
+
+### Key Architectural Decisions
+
+1. **Microservices**: Each major feature is a separate service for scalability
+2. **Blockchain Integration**: Ethereum smart contracts for immutable certificates
+3. **Hybrid Storage**: MongoDB for application data, IPFS for decentralized storage
+4. **JWT Authentication**: Stateless authentication with wallet-based identity
+5. **Real-Time Processing**: WebSocket connections for live updates
+6. **Containerization**: Docker for consistent deployment across environments
+
+---
+
+## 🔧 Technology Stack
+
+### Frontend
+- **Framework**: Next.js 14 (React 18)
+- **Language**: TypeScript
+- **Styling**: TailwindCSS
+- **UI Components**: Radix UI, shadcn/ui
+- **State Management**: React Context + Hooks
+- **Web3 Integration**: 
+  - ethers.js / web3.js
+  - MetaMask SDK
+  - wagmi (React Hooks for Ethereum)
+- **Charts & Visualization**: Chart.js, Recharts
+- **Forms**: React Hook Form + Zod validation
+- **HTTP Client**: Axios
+- **Animations**: Framer Motion
+
+### Backend
+- **Framework**: Flask 2.3.3 (Python)
+- **Async Support**: asyncio, motor (async MongoDB driver)
+- **API Type**: REST + WebSocket
+- **Authentication**: 
+  - Flask-JWT-Extended
+  - Wallet signature verification (Web3)
+- **CORS**: Flask-CORS
+- **Environment**: python-dotenv
+
+### Database
+- **Primary**: MongoDB 6.0+
+  - Document-based storage for flexible schemas
+  - Collections: users, courses, quizzes, certificates, submissions
+- **Cache**: Redis 7
+  - Session management
+  - Rate limiting
+  - Temporary data storage
+- **Future**: PostgreSQL (planned for relational data)
+
+### Blockchain
+- **Smart Contract Language**: Solidity 0.8.19
+- **Development Framework**: Foundry
+  - forge (testing and building)
+  - anvil (local Ethereum node)
+  - cast (CLI for contract interaction)
+- **Smart Contract Standards**: 
+  - ERC-721 (NFT certificates)
+  - OpenZeppelin contracts (security-audited base contracts)
+- **Network**: 
+  - Local: Anvil (development)
+  - Production: Ethereum mainnet / L2 solutions (Polygon, Arbitrum)
+
+### Machine Learning
+- **Framework**: TensorFlow 2.17, Keras 3.2
+- **Data Processing**: NumPy, Pandas, scikit-learn
+- **NLP**: (for question generation and analysis)
+- **Adaptive Algorithm**: Custom implementation with reinforcement learning principles
+
+### DevOps
+- **Containerization**: Docker, Docker Compose
+- **CI/CD**: GitHub Actions (implied)
+- **Deployment**: 
+  - Single-server: deploy-single.sh script
+  - Container orchestration ready
+- **Monitoring**: Application logs, TensorFlow metrics
+
+### Security
+- **Encryption**: PyCryptodome (AES encryption)
+- **Password Hashing**: passlib with bcrypt
+- **JWT**: PyJWT with cryptographic signatures
+- **Web3 Security**: eth-account for signature verification
+- **Secure Code Execution**: Sandboxed Docker containers for code compilation
+
+---
+
+## 📁 Project Structure
+
+```
+OpenLearnX/
+├── backend/                      # Flask backend application
+│   ├── main.py                   # Application entry point
+│   ├── requirements.txt          # Python dependencies
+│   │
+│   ├── contracts/                # Solidity smart contracts
+│   │   └── CertificateNFT.sol   # ERC-721 NFT certificate contract
+│   │
+│   ├── routes/                   # API route handlers
+│   │   ├── auth.py              # Authentication endpoints
+│   │   ├── quizzes.py           # Quiz management
+│   │   ├── adaptive_quiz.py     # Adaptive testing
+│   │   ├── certificate.py       # NFT certificate minting
+│   │   ├── dashboard.py         # Analytics and dashboards
+│   │   ├── compiler.py          # Code compilation service
+│   │   ├── coding.py            # Coding challenges
+│   │   ├── exam.py              # Examination system
+│   │   ├── courses.py           # Course management
+│   │   ├── admin.py             # Admin panel
+│   │   └── test_flow.py         # Testing workflows
+│   │
+│   ├── services/                 # Business logic layer
+│   │   ├── ai_quiz_service.py   # AI-powered quiz generation
+│   │   ├── adaptive_quiz_service.py  # Adaptive algorithm
+│   │   ├── compiler_service.py  # Code compilation logic
+│   │   ├── real_compiler_service.py  # Real code execution
+│   │   ├── dashboard_service.py # Dashboard data aggregation
+│   │   └── wallet_service.py    # Web3 wallet interactions
+│   │
+│   ├── models/                   # Data models
+│   │   ├── user.py              # User data model
+│   │   ├── certificate.py       # Certificate model
+│   │   └── dashboard_models.py  # Dashboard data structures
+│   │
+│   ├── utils/                    # Utility functions
+│   │   └── adaptive_engine.py   # Adaptive learning engine
+│   │
+│   ├── scripts/                  # Deployment and utility scripts
+│   │   └── deploy.py            # Smart contract deployment
+│   │
+│   ├── llmtrain/                 # ML model training
+│   ├── cache/                    # Temporary cache
+│   ├── mongo_service.py         # MongoDB connection service
+│   ├── web3_service.py          # Web3 blockchain service
+│   ├── quiz_master.py           # Quiz orchestration
+│   ├── seed_courses.py          # Database seeding
+│   │
+│   ├── foundry.toml             # Foundry configuration
+│   ├── deployment.json          # Contract deployment info
+│   └── Dockerfile               # Backend container config
+│
+├── frontend/                     # Next.js frontend application
+│   ├── app/                     # Next.js 14 app directory
+│   │   ├── page.tsx             # Home page
+│   │   ├── layout.tsx           # Root layout
+│   │   ├── globals.css          # Global styles
+│   │   │
+│   │   ├── auth/                # Authentication pages
+│   │   ├── dashboard/           # Dashboard pages
+│   │   ├── certificate/         # Certificate gallery
+│   │   ├── courses/             # Course browsing
+│   │   ├── coding/              # Code challenges
+│   │   ├── compiler/            # Online compiler
+│   │   ├── adaptive-quiz/       # Adaptive tests
+│   │   ├── join-test/           # Test joining flow
+│   │   └── admin/               # Admin panel
+│   │
+│   ├── components/              # Reusable React components
+│   │   └── ui/                  # shadcn/ui components
+│   │
+│   ├── context/                 # React Context providers
+│   ├── hooks/                   # Custom React hooks
+│   ├── lib/                     # Utility libraries
+│   ├── styles/                  # Additional styles
+│   │
+│   ├── package.json             # Node.js dependencies
+│   ├── tsconfig.json            # TypeScript configuration
+│   ├── tailwind.config.ts       # TailwindCSS configuration
+│   ├── next.config.mjs          # Next.js configuration
+│   └── components.json          # shadcn/ui config
+│
+├── chatApp/                      # Decentralized chat feature
+│   ├── chatApp.sol              # Chat smart contract
+│   ├── index.html               # Chat interface
+│   ├── account.html             # Account management
+│   └── styles.css               # Chat styling
+│
+├── .wake/                        # Wake AI agent configuration
+│
+├── docker-compose.yml           # Multi-container orchestration
+├── Dockerfile                   # Main application container
+├── deploy-single.sh             # Single-server deployment script
+├── requirements.txt             # Python dependencies (root)
+├── README.md                    # Project overview
+├── steps.md                     # Setup instructions
+├── .gitignore                   # Git ignore rules
+├── .dockerignore                # Docker ignore rules
+└── .gitmodules                  # Git submodules (OpenZeppelin)
+```
+
+---
+
+## 📜 Smart Contracts
+
+### CertificateNFT Contract
+
+**Purpose**: Issue tamper-proof, blockchain-verified certificates as NFTs.
+
+**Key Features**:
+- ERC-721 compliant (standard NFT)
+- Stores certificate metadata on-chain
+- Tracks certificate ownership
+- Verifiable by anyone on the blockchain
+
+**Contract Structure**:
+```solidity
+contract CertificateNFT is ERC721, ERC721URIStorage, Ownable {
+    struct Certificate {
+        string subject;        // Course/subject name
+        string studentName;    // Learner name
+        uint256 score;         // Achievement score
+        uint256 timestamp;     // Issue date
+        bool verified;         // Verification status
+    }
+    
+    // Main functions:
+    - mintCertificate(address to, string tokenURI)
+    - mintCertificateWithDetails(...)
+    - getCertificate(uint256 tokenId)
+    - getUserCertificates(address user)
+    - verifyCertificate(uint256 tokenId)
+}
+```
+
+**Key Functions**:
+
+1. **mintCertificate**: Creates a basic certificate NFT
+   - Only owner (platform) can mint
+   - Assigns to learner's wallet
+   - Returns token ID
+
+2. **mintCertificateWithDetails**: Creates detailed certificate
+   - Includes subject, name, score
+   - Timestamp automatically set
+   - Emits CertificateMinted event
+
+3. **verifyCertificate**: Public verification
+   - Anyone can check authenticity
+   - Returns verification status
+
+4. **getUserCertificates**: Get all certificates for a wallet
+   - Returns array of token IDs
+   - Used for portfolio display
+
+**Deployment**:
+- Deployed using Foundry (forge)
+- Uses OpenZeppelin audited base contracts
+- Deployed on local Anvil node for development
+- Ready for mainnet/L2 deployment
+
+---
+
+## 🖥 Backend Services
+
+### 1. Authentication Service (`routes/auth.py`)
+
+**Endpoints**:
+- `POST /api/auth/nonce` - Generate nonce for wallet signature
+- `POST /api/auth/verify` - Verify wallet signature and issue JWT
+- `POST /api/auth/register` - Register new user with wallet
+- `GET /api/auth/profile` - Get user profile (requires JWT)
+
+**Authentication Flow**:
+```
+1. User connects MetaMask wallet
+2. Frontend requests nonce from backend
+3. User signs nonce with private key
+4. Backend verifies signature matches wallet address
+5. Backend issues JWT token
+6. JWT used for subsequent requests
+```
+
+**Security**:
+- Wallet-based authentication (no passwords)
+- Time-limited nonces (prevent replay attacks)
+- JWT with expiration
+- Signature verification using eth-account
+
+### 2. Quiz Service (`routes/quizzes.py`)
+
+**Features**:
+- Create, read, update, delete quizzes
+- Multiple question types (MCQ, coding, essay)
+- Auto-grading for objective questions
+- Manual grading interface for subjective questions
+- Quiz attempt tracking
+- Time limits and deadlines
+
+**Endpoints**:
+- `POST /api/quizzes` - Create quiz
+- `GET /api/quizzes` - List all quizzes
+- `GET /api/quizzes/:id` - Get quiz details
+- `POST /api/quizzes/:id/attempt` - Submit quiz attempt
+- `GET /api/quizzes/:id/results` - Get results
+
+### 3. Adaptive Quiz Service (`routes/adaptive_quiz.py`)
+
+**Adaptive Algorithm**:
+- Uses Item Response Theory (IRT)
+- Adjusts question difficulty based on performance
+- Estimates learner ability in real-time
+- Provides personalized question selection
+
+**How It Works**:
+```python
+1. Start with medium difficulty question
+2. If correct → increase difficulty
+3. If incorrect → decrease difficulty
+4. Track ability estimate (theta)
+5. Select next question optimally for ability level
+6. Repeat until convergence or question limit
+```
+
+**Endpoints**:
+- `POST /api/adaptive-quiz/start` - Start adaptive test
+- `POST /api/adaptive-quiz/answer` - Submit answer, get next question
+- `GET /api/adaptive-quiz/results` - Final results and ability estimate
+
+### 4. Certificate Service (`routes/certificate.py`)
+
+**Certificate Issuance Flow**:
+```
+1. User completes quiz/course
+2. Backend verifies completion and score
+3. Generate certificate metadata (JSON)
+4. Upload metadata to IPFS
+5. Call smart contract to mint NFT
+6. Store transaction hash in database
+7. Return certificate to user
+```
+
+**Endpoints**:
+- `POST /api/certificates/mint` - Mint new certificate
+- `GET /api/certificates/:id` - Get certificate details
+- `GET /api/certificates/user/:wallet` - Get user's certificates
+- `GET /api/certificates/verify/:tokenId` - Verify certificate on blockchain
+
+**IPFS Integration**:
+- Metadata stored on IPFS for permanence
+- Contains: name, subject, score, issue date, image
+- IPFS hash stored in smart contract
+- Ensures data can't be lost or altered
+
+### 5. Compiler Service (`routes/compiler.py`)
+
+**Supported Languages**:
+- Python (3.x)
+- JavaScript (Node.js)
+- Java
+- C++, C
+- Go
+- Rust
+- Ruby
+- PHP
+
+**Execution Flow**:
+```
+1. Receive code and language from frontend
+2. Create isolated Docker container
+3. Write code to file inside container
+4. Compile (if needed)
+5. Execute with resource limits (CPU, memory, time)
+6. Capture stdout, stderr
+7. Return output to user
+8. Clean up container
+```
+
+**Security Features**:
+- Sandboxed execution (Docker)
+- Resource limits (prevent infinite loops)
+- Network isolation
+- No file system access outside container
+- Timeout enforcement
+
+**Endpoints**:
+- `POST /api/compiler/run` - Execute code
+- `POST /api/compiler/test` - Run against test cases
+
+### 6. Dashboard Service (`routes/dashboard.py`)
+
+**Analytics Provided**:
+- Overall progress percentage
+- Competency radar chart (skill distribution)
+- Time series of performance
+- Subject-wise breakdown
+- Recent activity timeline
+- Strengths and weaknesses
+
+**Student Dashboard**:
+- My courses and progress
+- Recent quiz scores
+- Certificates earned
+- Upcoming deadlines
+- Recommended next steps
+
+**Instructor Dashboard**:
+- Class average performance
+- Student progress tracking
+- Question statistics (difficulty, discrimination)
+- Grading queue
+- Bias detection alerts
+
+**Endpoints**:
+- `GET /api/dashboard/student` - Student analytics
+- `GET /api/dashboard/instructor` - Instructor analytics
+- `GET /api/dashboard/competency` - Competency mapping
+
+### 7. AI Quiz Service (`services/ai_quiz_service.py`)
+
+**Question Generation**:
+- Uses TensorFlow models
+- Generates contextual questions based on topic
+- Validates question quality
+- Creates distractors (wrong answers) for MCQs
+
+**Features**:
+- Topic-based generation
+- Difficulty control
+- Question type variety
+- Quality scoring
+
+---
+
+## 🎨 Frontend Application
+
+### Key Pages
+
+#### 1. Home Page (`app/page.tsx`)
+- Platform introduction
+- Feature highlights
+- Call to action (Connect Wallet)
+- Statistics (users, certificates issued, courses)
+
+#### 2. Authentication (`app/auth/`)
+- MetaMask connection
+- Wallet signature verification
+- User registration flow
+- Profile management
+
+#### 3. Dashboard (`app/dashboard/`)
+- Progress overview
+- Recent activity
+- Quick actions
+- Performance charts
+
+#### 4. Courses (`app/courses/`)
+- Course catalog
+- Course details
+- Enrollment
+- Course progress
+
+#### 5. Adaptive Quiz (`app/adaptive-quiz/`)
+- Quiz interface
+- Real-time difficulty adjustment
+- Instant feedback
+- Progress indicator
+
+#### 6. Coding Challenges (`app/coding/`)
+- Problem description
+- Code editor (Monaco Editor)
+- Test cases
+- Submission and results
+
+#### 7. Online Compiler (`app/compiler/`)
+- Multi-language support
+- Live code execution
+- Output display
+- Error handling
+
+#### 8. Certificate Gallery (`app/certificate/`)
+- User's certificates
+- Blockchain verification
+- Download/share options
+- QR code for verification
+
+#### 9. Admin Panel (`app/admin/`)
+- User management
+- Course creation
+- Quiz authoring
+- Analytics and reports
+
+### Key Components
+
+**UI Components** (shadcn/ui):
+- Buttons, Cards, Dialogs
+- Forms, Inputs, Selects
+- Tables, Tabs, Toast notifications
+- Accordions, Alerts, Avatars
+
+**Custom Components**:
+- WalletConnect: MetaMask integration
+- QuestionCard: Quiz question display
+- CodeEditor: Syntax-highlighted editor
+- ProgressChart: Performance visualization
+- CertificateCard: NFT certificate display
+
+---
+
+## 💾 Database Schema
+
+### MongoDB Collections
+
+#### 1. users
+```json
+{
+  "_id": ObjectId,
+  "wallet_address": "0x...",
+  "username": "string",
+  "email": "string",
+  "role": "student|instructor|admin",
+  "created_at": ISODate,
+  "profile": {
+    "name": "string",
+    "bio": "string",
+    "avatar": "string"
+  },
+  "stats": {
+    "quizzes_completed": 0,
+    "certificates_earned": 0,
+    "total_score": 0
+  }
+}
+```
+
+#### 2. courses
+```json
+{
+  "_id": ObjectId,
+  "title": "string",
+  "description": "string",
+  "instructor_id": ObjectId,
+  "topics": ["array of strings"],
+  "difficulty": "beginner|intermediate|advanced",
+  "created_at": ISODate,
+  "quizzes": ["array of quiz IDs"],
+  "enrollments": 0
+}
+```
+
+#### 3. quizzes
+```json
+{
+  "_id": ObjectId,
+  "course_id": ObjectId,
+  "title": "string",
+  "description": "string",
+  "questions": [
+    {
+      "id": "string",
+      "type": "mcq|coding|essay",
+      "question": "string",
+      "options": ["array"],
+      "correct_answer": "string|array",
+      "points": 0,
+      "difficulty": 0.0-1.0
+    }
+  ],
+  "time_limit": 3600,
+  "passing_score": 70,
+  "adaptive": true|false
+}
+```
+
+#### 4. quiz_attempts
+```json
+{
+  "_id": ObjectId,
+  "quiz_id": ObjectId,
+  "user_id": ObjectId,
+  "started_at": ISODate,
+  "completed_at": ISODate,
+  "answers": [
+    {
+      "question_id": "string",
+      "user_answer": "string",
+      "is_correct": true|false,
+      "points_earned": 0
+    }
+  ],
+  "score": 0,
+  "percentage": 0.0,
+  "ability_estimate": 0.0,
+  "passed": true|false
+}
+```
+
+#### 5. certificates
+```json
+{
+  "_id": ObjectId,
+  "user_id": ObjectId,
+  "wallet_address": "0x...",
+  "course_id": ObjectId,
+  "quiz_id": ObjectId,
+  "token_id": 0,
+  "transaction_hash": "0x...",
+  "ipfs_hash": "string",
+  "subject": "string",
+  "score": 0,
+  "issued_at": ISODate,
+  "metadata": {
+    "name": "string",
+    "description": "string",
+    "image": "string"
+  }
+}
+```
+
+---
+
+## 🔌 API Documentation
+
+### Base URL
+```
+Development: http://localhost:5000/api
+Production: https://your-domain.com/api
+```
+
+### Authentication
+All protected endpoints require JWT token in header:
+```
+Authorization: Bearer <jwt_token>
+```
+
+### Common Response Format
+```json
+{
+  "success": true|false,
+  "data": {},
+  "message": "string",
+  "error": "string" // only on failure
+}
+```
+
+### Endpoint Summary
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+| **Authentication** ||||
+| POST | /auth/nonce | Get nonce for wallet signature | No |
+| POST | /auth/verify | Verify signature and get JWT | No |
+| POST | /auth/register | Register new user | No |
+| GET | /auth/profile | Get user profile | Yes |
+| **Quizzes** ||||
+| GET | /quizzes | List all quizzes | No |
+| GET | /quizzes/:id | Get quiz details | Yes |
+| POST | /quizzes/:id/attempt | Submit quiz attempt | Yes |
+| GET | /quizzes/:id/results | Get quiz results | Yes |
+| **Adaptive Quiz** ||||
+| POST | /adaptive-quiz/start | Start adaptive test | Yes |
+| POST | /adaptive-quiz/answer | Submit answer | Yes |
+| GET | /adaptive-quiz/results | Get final results | Yes |
+| **Certificates** ||||
+| POST | /certificates/mint | Mint certificate | Yes |
+| GET | /certificates/user/:wallet | Get user certificates | No |
+| GET | /certificates/verify/:tokenId | Verify certificate | No |
+| **Compiler** ||||
+| POST | /compiler/run | Execute code | Yes |
+| POST | /compiler/test | Run test cases | Yes |
+| **Dashboard** ||||
+| GET | /dashboard/student | Student analytics | Yes |
+| GET | /dashboard/instructor | Instructor analytics | Yes |
+| **Courses** ||||
+| GET | /courses | List courses | No |
+| GET | /courses/:id | Get course details | No |
+| POST | /courses/:id/enroll | Enroll in course | Yes |
+
+---
+
+## ⚙️ Setup & Installation
+
+### Prerequisites
+- **Operating System**: Linux, macOS, or WSL (Windows Subsystem for Linux)
+- **Node.js**: v18+ (for frontend)
+- **Python**: 3.10+ (for backend)
+- **MongoDB**: 6.0+ (database)
+- **Docker**: 20.10+ (optional, for containerized deployment)
+- **Git**: For cloning repository
+- **MetaMask**: Browser extension for Web3
+
+### Step-by-Step Installation
+
+#### 1. Install Foundry (Blockchain Development Toolkit)
+
+```bash
+# Install Foundry
+curl -L https://foundry.paradigm.xyz | bash
+
+# Reload shell configuration
+source ~/.bashrc  # or source ~/.zshrc
+
+# Install Foundry toolchain
+foundryup
+
+# Verify installation
+forge --version
+anvil --version
+cast --version
+```
+
+#### 2. Clone Repository
+
+```bash
+git clone https://github.com/th30d4y/OpenLearnX.git
+cd OpenLearnX
+```
+
+#### 3. Backend Setup
+
+```bash
+cd backend
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy environment template
+cp .env.example .env  # Create this if it doesn't exist
+
+# Edit .env with your settings
+nano .env
+```
+
+**Required Environment Variables** (`.env`):
+```env
+# Flask
+FLASK_APP=main.py
+FLASK_ENV=development
+SECRET_KEY=your-secret-key-here
+
+# MongoDB
+MONGODB_URI=mongodb://localhost:27017/openlearnx
+
+# Redis (optional)
+REDIS_URL=redis://localhost:6379
+
+# Web3
+WEB3_PROVIDER_URL=http://127.0.0.1:8545
+CONTRACT_ADDRESS=0x... # Set after deploying contract
+
+# IPFS (optional)
+IPFS_GATEWAY=https://ipfs.io/ipfs/
+
+# JWT
+JWT_SECRET_KEY=your-jwt-secret
+JWT_ACCESS_TOKEN_EXPIRES=3600
+```
+
+#### 4. Start Local Blockchain
+
+**Terminal 1** - Run Anvil:
+```bash
+anvil --fork-url https://eth.merkle.io
+```
+
+This starts a local Ethereum node. Keep this running.
+
+**Output**:
+```
+Available Accounts
+==================
+(0) 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
+(1) 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH)
+...
+
+Private Keys
+==================
+(0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+...
+
+Chain ID
+==================
+31337
+```
+
+#### 5. Deploy Smart Contract
+
+**Terminal 2**:
+```bash
+cd backend
+source venv/bin/activate
+
+# Deploy contract
+python3 scripts/deploy.py
+```
+
+**Output**:
+```
+Deploying CertificateNFT contract...
+Contract deployed at: 0x5FbDB2315678afecb367f032d93F642f64180aa3
+Transaction hash: 0x...
+```
+
+**Important**: Copy the contract address to your `.env` file:
+```env
+CONTRACT_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
+```
+
+#### 6. Start Backend Server
+
+**Terminal 3**:
+```bash
+cd backend
+source venv/bin/activate
+
+# Seed database (optional)
+python3 seed_courses.py
+
+# Start Flask app
+python3 main.py
+```
+
+**Output**:
+```
+ * Running on http://127.0.0.1:5000
+ * Running on http://192.168.x.x:5000
+```
+
+**Test Backend**:
+```bash
+# Health check
+curl http://127.0.0.1:5000/
+
+# Test nonce generation
+curl -X POST http://127.0.0.1:5000/api/auth/nonce \
+  -H "Content-Type: application/json" \
+  -d '{"wallet_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"}'
+```
+
+#### 7. Install MongoDB
+
+**Linux (Arch)**:
+```bash
+yay -S mongodb-bin
+sudo systemctl start mongodb
+sudo systemctl enable mongodb
+mongosh  # Test connection
+```
+
+**macOS**:
+```bash
+brew tap mongodb/brew
+brew install mongodb-community
+brew services start mongodb-community
+mongosh  # Test connection
+```
+
+**Docker**:
+```bash
+docker run -d -p 27017:27017 --name mongodb mongo:6
+```
+
+#### 8. Frontend Setup
+
+**Terminal 4**:
+```bash
+cd frontend
+
+# Install dependencies
+pnpm install
+# or: npm install
+
+# Copy environment template
+cp .env.example .env.local
+
+# Edit .env.local
+nano .env.local
+```
+
+**Frontend Environment Variables** (`.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
+```
+
+**Start Frontend**:
+```bash
+pnpm run dev
+# or: npm run dev
+```
+
+**Output**:
+```
+▲ Next.js 14.0.0
+- Local:        http://localhost:3000
+- Network:      http://192.168.x.x:3000
+```
+
+#### 9. Access Application
+
+1. Open browser: http://localhost:3000
+2. Install MetaMask extension if not already installed
+3. Add local network to MetaMask:
+   - Network Name: Anvil Local
+   - RPC URL: http://127.0.0.1:8545
+   - Chain ID: 31337
+   - Currency Symbol: ETH
+4. Import account using private key from Anvil
+5. Connect wallet on homepage
+6. Start learning!
+
+---
+
+## 🚀 Deployment
+
+### Docker Deployment
+
+#### Option 1: Docker Compose (Recommended)
+
+**Includes**: Application, MongoDB, Redis, all in one command
+
+```bash
+# Build and start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+```
+
+**Access**:
+- Application: http://localhost:80
+- MongoDB: localhost:5432
+- Redis: localhost:6379
+
+#### Option 2: Single Container
+
+```bash
+# Build image
+docker build -t openlearnx .
+
+# Run container
+docker run -d -p 80:80 \
+  -e DATABASE_URL=mongodb://host.docker.internal:27017/openlearnx \
+  -e CONTRACT_ADDRESS=0x... \
+  --name openlearnx \
+  openlearnx
+```
+
+### Production Deployment
+
+#### Prerequisites
+- VPS or cloud server (AWS, DigitalOcean, etc.)
+- Domain name
+- SSL certificate (Let's Encrypt)
+
+#### Deployment Script
+
+The project includes `deploy-single.sh` for single-server deployment:
+
+```bash
+# Make script executable
+chmod +x deploy-single.sh
+
+# Run deployment
+./deploy-single.sh
+```
+
+**Script performs**:
+1. Updates system packages
+2. Installs dependencies
+3. Clones repository
+4. Sets up Python environment
+5. Installs Node.js packages
+6. Configures MongoDB
+7. Deploys smart contract
+8. Starts services
+9. Sets up Nginx reverse proxy
+10. Configures SSL
+
+#### Manual Production Setup
+
+**1. Server Setup**:
+```bash
+# Update system
+sudo apt update && sudo apt upgrade -y
+
+# Install dependencies
+sudo apt install -y python3 python3-pip nodejs npm mongodb nginx
+
+# Install Foundry
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+```
+
+**2. Clone and Configure**:
+```bash
+cd /opt
+sudo git clone https://github.com/th30d4y/OpenLearnX.git
+cd OpenLearnX
+
+# Backend
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Frontend
+cd ../frontend
+npm install
+npm run build
+```
+
+**3. Deploy Contract** (if using public network):
+```bash
+# Set up Ethereum node or use Alchemy/Infura
+# Update deploy script with production network
+cd backend
+python3 scripts/deploy.py --network mainnet
+```
+
+**4. Configure Nginx**:
+```nginx
+# /etc/nginx/sites-available/openlearnx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Frontend
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Backend API
+    location /api {
+        proxy_pass http://localhost:5000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+```bash
+# Enable site
+sudo ln -s /etc/nginx/sites-available/openlearnx /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+
+# Setup SSL
+sudo certbot --nginx -d your-domain.com
+```
+
+**5. Process Management** (systemd):
+
+Backend service (`/etc/systemd/system/openlearnx-backend.service`):
+```ini
+[Unit]
+Description=OpenLearnX Backend
+After=network.target mongodb.service
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/OpenLearnX/backend
+Environment="PATH=/opt/OpenLearnX/backend/venv/bin"
+ExecStart=/opt/OpenLearnX/backend/venv/bin/python main.py
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Frontend service (`/etc/systemd/system/openlearnx-frontend.service`):
+```ini
+[Unit]
+Description=OpenLearnX Frontend
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/OpenLearnX/frontend
+Environment="NODE_ENV=production"
+ExecStart=/usr/bin/npm start
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+# Start services
+sudo systemctl daemon-reload
+sudo systemctl enable openlearnx-backend openlearnx-frontend
+sudo systemctl start openlearnx-backend openlearnx-frontend
+```
+
+---
+
+## 🔒 Security Features
+
+### 1. Wallet-Based Authentication
+- No passwords to leak or hack
+- Cryptographic signature verification
+- User owns their identity (wallet)
+- Prevents phishing attacks
+
+### 2. Smart Contract Security
+- Uses OpenZeppelin audited contracts
+- Access control (only owner can mint)
+- Non-transferable certificates (soulbound tokens)
+- Immutable once minted
+
+### 3. Code Execution Sandbox
+- Docker containerization
+- Resource limits (CPU, memory, time)
+- No network access
+- Read-only file system
+- Process isolation
+
+### 4. Data Encryption
+- AES encryption for sensitive data
+- HTTPS/TLS in production
+- JWT with signature verification
+- Encrypted database connections
+
+### 5. Input Validation
+- All inputs sanitized
+- SQL injection prevention (using ORM)
+- XSS protection
+- CSRF tokens
+
+### 6. Rate Limiting
+- API rate limits (Redis)
+- Prevents DDoS attacks
+- Per-user request limits
+- Gradual backoff
+
+### 7. Secure File Handling
+- File type validation
+- Size limits
+- Virus scanning (production)
+- Isolated storage
+
+### 8. Audit Logging
+- All critical actions logged
+- User activity tracking
+- Security event monitoring
+- Compliance ready
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to get started:
+
+### Development Workflow
+
+1. **Fork the Repository**
+   ```bash
+   # Click "Fork" on GitHub
+   git clone https://github.com/YOUR_USERNAME/OpenLearnX.git
+   ```
+
+2. **Create Feature Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make Changes**
+   - Write clean, documented code
+   - Follow existing code style
+   - Add tests for new features
+   - Update documentation
+
+4. **Test Locally**
+   ```bash
+   # Backend tests
+   cd backend
+   pytest
+
+   # Frontend tests
+   cd frontend
+   npm test
+   ```
+
+5. **Commit Changes**
+   ```bash
+   git add .
+   git commit -m "feat: add new adaptive algorithm"
+   ```
+
+   **Commit Message Format**:
+   - `feat:` - New feature
+   - `fix:` - Bug fix
+   - `docs:` - Documentation changes
+   - `style:` - Code style changes
+   - `refactor:` - Code refactoring
+   - `test:` - Test changes
+   - `chore:` - Build/tool changes
+
+6. **Push and Create PR**
+   ```bash
+   git push origin feature/your-feature-name
+   # Open Pull Request on GitHub
+   ```
+
+### Code Style Guidelines
+
+**Python**:
+- Follow PEP 8
+- Use type hints
+- Write docstrings for functions
+- Maximum line length: 88 characters (Black formatter)
+
+**TypeScript/React**:
+- Use TypeScript strict mode
+- Functional components with hooks
+- ESLint and Prettier compliant
+- Meaningful component names
+
+**Smart Contracts**:
+- Follow Solidity style guide
+- Extensive comments
+- Gas optimization
+- Security first
+
+### Areas for Contribution
+
+- 🐛 Bug fixes
+- ✨ New features
+- 📚 Documentation improvements
+- 🌐 Translations/i18n
+- 🎨 UI/UX enhancements
+- ⚡ Performance optimizations
+- 🧪 Test coverage
+- 🔒 Security audits
+
+---
+
+## 📊 Project Status & Roadmap
+
+### Current Status
+✅ **Alpha Release** - Core features functional, under active development
+
+### Completed Features
+- [x] Wallet authentication
+- [x] Basic quiz system
+- [x] Adaptive testing algorithm
+- [x] NFT certificate minting
+- [x] Multi-language compiler
+- [x] Student dashboard
+- [x] Course management
+- [x] Admin panel
+
+### In Progress
+- [ ] AI question generation refinement
+- [ ] Peer review system
+- [ ] Enhanced analytics
+- [ ] Mobile app (React Native)
+
+### Planned Features
+- [ ] Live proctoring for exams
+- [ ] Video lessons integration
+- [ ] Gamification (badges, leaderboards)
+- [ ] Social features (study groups, forums)
+- [ ] Marketplace for courses
+- [ ] Integration with job platforms
+- [ ] Multi-language support (i18n)
+- [ ] Offline mode (PWA)
+- [ ] AI tutor chatbot
+- [ ] Advanced bias detection
+
+---
+
+## 📞 Support & Community
+
+### Getting Help
+- 📖 **Documentation**: This file and inline code comments
+- 💬 **Discussions**: GitHub Discussions tab
+- 🐛 **Issues**: GitHub Issues for bug reports
+- 📧 **Email**: [Project maintainer email]
+
+### Community Guidelines
+- Be respectful and inclusive
+- Help others learn and grow
+- Share knowledge freely
+- Report security issues privately
+
+---
+
+## 📄 License
+
+[Include license information here - e.g., MIT, Apache 2.0]
+
+---
+
+## 🙏 Acknowledgments
+
+- **OpenZeppelin**: Secure smart contract libraries
+- **Foundry**: Blazing fast Ethereum development toolkit
+- **Next.js**: React framework for production
+- **TensorFlow**: Machine learning framework
+- **MongoDB**: Flexible database solution
+- **shadcn/ui**: Beautiful component library
+- **All Contributors**: Thank you for making OpenLearnX better!
+
+---
+
+## 📈 Statistics
+
+- **Lines of Code**: ~8,000+ (backend Python)
+- **Smart Contracts**: 1 deployed (CertificateNFT)
+- **API Endpoints**: 30+
+- **Supported Languages**: 8+ (compiler)
+- **Dependencies**: 
+  - Python: 50+ packages
+  - Node.js: 60+ packages
+- **Database Collections**: 6 primary collections
+
+---
+
+## 🔮 Vision for the Future
+
+OpenLearnX aims to become the **de facto standard for verifiable online learning**. We envision a world where:
+
+1. **Every learner** owns their educational data and credentials
+2. **Employers** can instantly verify candidate skills
+3. **Education** is accessible, personalized, and continuous
+4. **Certificates** are globally recognized and tamper-proof
+5. **Learning** adapts to individual needs in real-time
+
+Join us in revolutionizing education! 🚀
+
+---
+
+**Last Updated**: 2026-01-31
+**Version**: 1.0.0
+**Maintainer**: OpenLearnX Team
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! 🎓**
diff --git a/README.md b/README.md
index 7f388b1..4750ad7 100644
--- a/README.md
+++ b/README.md
@@ -1,43 +1,267 @@
 # OpenLearnX
 
-**OpenLearnX** is a decentralized learning and assessment platform that blends adaptive testing, instant feedback, and blockchain-based certification.
+**OpenLearnX** is a cutting-edge decentralized learning and assessment platform that revolutionizes education through adaptive testing, instant feedback, and blockchain-based certification.
 
-The goal is to give learners a smarter, personalized, and verifiable way to build and prove skills — from code challenges to real-world learning paths.
+The platform provides learners with a smarter, personalized, and verifiable way to build and prove skills — from code challenges to real-world learning paths, all backed by blockchain technology.
+
+> 📚 **Documentation**: [DOCS_INDEX.md](./DOCS_INDEX.md) | [DOCUMENTATION.md](./DOCUMENTATION.md) | [QUICK_START.md](./QUICK_START.md)
 
 ---
 
 ## ✨ What Makes It Different?
 
-- **Adaptive Learning:** Challenges that scale with your skill level.
-- **Instant Feedback:** Get results and explanations right away.
-- **Blockchain Certificates:** Earn NFTs as proof of learning.
-- **Skill Dashboard:** Track progress over time, transparently.
-- **Decentralized Storage:** Own your data, powered by IPFS.
+- **🎯 Adaptive Learning:** Challenges that scale dynamically with your skill level using advanced algorithms
+- **⚡ Instant Feedback:** Get results and detailed explanations in real-time
+- **🔐 Blockchain Certificates:** Earn tamper-proof NFT certificates as verifiable proof of learning
+- **📊 Skill Dashboard:** Track progress over time with comprehensive analytics and competency mapping
+- **🌐 Decentralized Storage:** Own your data with IPFS-powered decentralized storage
+- **💻 Multi-Language Compiler:** Execute code in 8+ programming languages with secure sandboxing
+- **🤖 AI-Powered Quizzes:** Intelligent question generation and adaptive difficulty adjustment
+- **👥 Peer Review System:** Collaborative learning with bias detection
 
 ---
 
 ## 📌 Use Cases
 
-- Coding challenges with verified results (like LeetCode + web3)
-- Course completions with on-chain badges
-- Portfolios linked to wallet identity
-- Verifiable skill progression
+- **Coding Bootcamps:** Verify student progress with blockchain certificates
+- **Professional Certification:** Issue tamper-proof credentials for completed courses
+- **Corporate Training:** Track employee skill development with transparent analytics
+- **Academic Assessments:** Adaptive testing that accurately measures student ability
+- **Portfolio Building:** Showcase verified skills to potential employers
+- **Skill Verification:** Employers can instantly verify candidate credentials on blockchain
+
+---
+
+## 🏗 Architecture Overview
+
+```
+Frontend (Next.js + React) → Backend (Flask + Python) → MongoDB Database
+                          ↓
+                    Web3 Layer (Ethereum)
+                          ↓
+              Smart Contracts (Solidity) → IPFS Storage
+```
+
+**Key Components:**
+- **Frontend**: Next.js 14, TypeScript, TailwindCSS, MetaMask integration
+- **Backend**: Flask, TensorFlow, Web3.py, JWT authentication
+- **Blockchain**: Solidity smart contracts, ERC-721 NFTs, Foundry toolkit
+- **Database**: MongoDB, Redis cache
+- **Storage**: IPFS for decentralized metadata
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Node.js 18+
+- Python 3.10+
+- MongoDB 6.0+
+- Docker (optional)
+- MetaMask browser extension
+
+### Installation
+
+1. **Install Foundry** (Blockchain toolkit):
+```bash
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+```
+
+2. **Clone the repository**:
+```bash
+git clone https://github.com/th30d4y/OpenLearnX.git
+cd OpenLearnX
+```
+
+3. **Start local blockchain** (Terminal 1):
+```bash
+anvil --fork-url https://eth.merkle.io
+```
+
+4. **Setup and start backend** (Terminal 2):
+```bash
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Deploy smart contract
+python3 scripts/deploy.py
+
+# Start backend server
+python3 main.py
+```
+
+5. **Setup and start frontend** (Terminal 3):
+```bash
+cd frontend
+pnpm install
+pnpm run dev
+```
+
+6. **Access the application**:
+   - Open http://localhost:3000
+   - Connect MetaMask wallet
+   - Start learning!
+
+> 📖 **For detailed setup instructions, see [DOCUMENTATION.md](./DOCUMENTATION.md#setup--installation)**
 
 ---
 
 ## 🌱 Project Status
 
-This is an early-stage open-source project under active development.  
-Join us, fork it, or suggest features — contributions are welcome!
+**Current Version**: Alpha 1.0.0  
+**Status**: 🟢 Active Development
+
+This is an open-source project under active development. Core features are functional, with continuous improvements being made.
+
+### Recent Updates
+- ✅ NFT certificate minting system
+- ✅ Adaptive quiz algorithm
+- ✅ Multi-language code compiler
+- ✅ Comprehensive dashboard analytics
+- ✅ Wallet-based authentication
+
+### Roadmap
+- 🔄 AI question generation refinement
+- 🔄 Peer review system enhancements
+- 📅 Mobile app (React Native)
+- 📅 Live proctoring for exams
+- 📅 Marketplace for courses
 
 ---
 
 ## 🧪 Built With
 
-- Solidity, Foundry, Anvil
-- React, Wagmi, TailwindCSS
-- IPFS / Web3.Storage
-- MetaMask wallet integration
+### Frontend
+- **Next.js 14** - React framework
+- **TypeScript** - Type safety
+- **TailwindCSS** - Styling
+- **shadcn/ui** - Component library
+- **ethers.js** - Ethereum interaction
+- **MetaMask SDK** - Wallet integration
+
+### Backend
+- **Flask** - Python web framework
+- **TensorFlow** - Machine learning
+- **MongoDB** - Database
+- **Redis** - Caching
+- **Web3.py** - Blockchain interaction
+- **Flask-JWT-Extended** - Authentication
+
+### Blockchain
+- **Solidity 0.8.19** - Smart contracts
+- **Foundry** - Development toolkit
+- **OpenZeppelin** - Secure contract libraries
+- **IPFS** - Decentralized storage
+- **Anvil** - Local Ethereum node
+
+---
+
+## 📊 Key Features
+
+### For Students
+- 🎓 Personalized adaptive learning paths
+- 💯 Instant feedback on assessments
+- 🏆 Blockchain-verified certificates (NFTs)
+- 📈 Progress tracking and analytics
+- 💻 Interactive coding challenges
+- 🌟 Skill competency mapping
+
+### For Instructors
+- 📚 Course creation and management
+- 👥 Student progress monitoring
+- 📊 Comprehensive analytics dashboard
+- ✍️ Quiz and assessment authoring
+- 🔍 Bias detection in grading
+- 📝 Automated and manual grading
+
+### For Employers
+- ✅ Instant credential verification
+- 🔗 Blockchain-backed authenticity
+- 📋 Detailed skill assessments
+- 🎯 Candidate skill mapping
+- 🔍 Transparent learning history
+
+---
+
+## 📚 Documentation
+
+Comprehensive documentation is available in [DOCUMENTATION.md](./DOCUMENTATION.md), including:
+
+- 📖 Detailed architecture explanation
+- 🔧 Technology stack deep dive
+- 📁 Project structure overview
+- 📜 Smart contract documentation
+- 🖥️ Backend services guide
+- 🎨 Frontend components reference
+- 💾 Database schema
+- 🔌 API documentation
+- ⚙️ Advanced configuration
+- 🚀 Production deployment guide
+- 🔒 Security best practices
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions from the community! Whether it's:
+
+- 🐛 Bug reports and fixes
+- ✨ New features
+- 📚 Documentation improvements
+- 🌐 Translations
+- 🎨 UI/UX enhancements
+- 🧪 Test coverage
+
+**How to contribute:**
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Please read [DOCUMENTATION.md](./DOCUMENTATION.md#contributing) for detailed contribution guidelines.
+
+---
+
+## 📄 License
+
+[Include your license here - e.g., MIT License]
+
+---
+
+## 🙏 Acknowledgments
+
+- **OpenZeppelin** - Secure smart contract libraries
+- **Foundry** - Ethereum development toolkit
+- **Next.js Team** - Amazing React framework
+- **TensorFlow** - Machine learning framework
+- **All Contributors** - Thank you for making OpenLearnX better!
+
+---
+
+## 📞 Contact & Support
+
+- 🌐 Website: [your-website.com]
+- 💬 Discord: [your-discord-link]
+- 🐦 Twitter: [@OpenLearnX]
+- 📧 Email: [your-email]
+- 📖 Docs: [DOCUMENTATION.md](./DOCUMENTATION.md)
+
+---
+
+## ⭐ Show Your Support
+
+If you find OpenLearnX useful, please consider:
+- ⭐ Starring this repository
+- 🔄 Sharing with others
+- 🐛 Reporting bugs
+- ✨ Contributing code
+- 💬 Joining our community
+
+**Together, let's revolutionize education! 🚀**
 
 ---