Enterprise LMS System - Complete Setup Guide

📋 Overview

This is an enterprise-grade Learning Management System with:

• Advanced RBAC (Role-Based Access Control) with hierarchical permissions
• JWT Authentication with session management
• MCP (Model Context Protocol) integration for AI-powered tools
• Intelligent UI with React
• Audit logging and security features
• Analytics dashboard with insights

---

🏗️ Architecture

┌─────────────────┐
│  React Frontend │ ← Modern UI with role-based views
└────────┬────────┘
         │ HTTP/REST
┌────────▼────────┐
│   FastAPI       │ ← Authentication, RBAC, Business Logic
│   Backend       │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼────┐ ┌─▼──────┐
│ SQLite │ │  MCP   │ ← AI-powered tools
│   DB   │ │ Server │
└────────┘ └────────┘

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 16+
• npm or yarn

1. Database Setup

cd database

# Create database and run migrations
python3 << EOF
import sqlite3
conn = sqlite3.connect('../db/lms.db')

# Read and execute schema
with open('schema.sql', 'r') as f:
    conn.executescript(f.read())

# Read and execute seed data
with open('seed_data.sql', 'r') as f:
    conn.executescript(f.read())

conn.close()
print("Database initialized successfully!")
EOF

2. Backend Setup

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

# Create .env file
cat > .env << EOF
DATABASE_URL=../db/lms.db
JWT_SECRET_KEY=your-super-secret-key-change-this-in-production
ENVIRONMENT=development
EOF

# Run backend
python main.py
# Backend will run on http://localhost:8000

3. MCP Server Setup

cd mcp_server

# Copy your lms_mcp_server.py file here
# Ensure it's executable
chmod +x lms_mcp_server.py

# Test MCP server
python lms_mcp_server.py add_course << EOF
{
  "course_id": "test_course",
  "title": "Test Course",
  "duration_weeks": 4,
  "level": "Beginner"
}
EOF

4. Frontend Setup

cd frontend

# Initialize React app (if not already done)
npm create vite@latest . -- --template react

# Install dependencies
npm install react-router-dom

# Copy App.jsx and App.css to src/

# Run development server
npm run dev
# Frontend will run on http://localhost:5173

---

👥 Default Users

Username	Password	Role	Permissions
admin	password123	Super Admin	All permissions
instructor_john	password123	Instructor	Course & student management
student_jane	password123	Student	View courses, self-enrollment

---

🔐 RBAC System

Role Hierarchy

1. Super Admin (Level 1) - Full system access
2. Admin (Level 2) - User & course management
3. Instructor (Level 3) - Course creation & teaching
4. Student (Level 4) - Learning & enrollment
5. Guest (Level 5) - Read-only access

Permission Format

Permissions follow the pattern: resource:action

Examples:

• course:create - Create courses
• course:read - View courses
• student:read_all - View all students
• analytics:read - View analytics

Key Features

• Hierarchical roles: Higher roles can manage lower roles
• Multi-role support: Users can have multiple roles
• Permission aggregation: Permissions from all roles are combined
• Resource-level ACL: Check ownership for specific resources
• Tool-permission mapping: MCP tools require specific permissions

---

🛠️ API Endpoints

Authentication

• POST /api/auth/login - Login with username/password
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/me - Get current user info
• POST /api/auth/logout - Logout

Courses

• POST /api/courses - Create course (requires course:create)
• GET /api/courses - List courses (requires course:read)
• GET /api/courses/{id} - Get course details

Enrollments

• POST /api/enrollments - Enroll student (requires enrollment:create)
• GET /api/enrollments - List enrollments (filtered by role)

Progress

• PUT /api/progress - Update progress (requires progress:update)

Users

• POST /api/users - Create user (requires user:create)
• GET /api/users - List users (requires user:read)
• POST /api/users/{id}/roles - Assign role (requires user:manage_roles)

Analytics

• GET /api/analytics/dashboard - Get dashboard stats (requires analytics:read)

MCP Tools

• GET /api/tools - List accessible tools
• POST /api/tools/{tool_name} - Execute tool (permission-checked)

---

🧠 Intelligence Features

1. Analytics Dashboard

• Total courses, students, enrollments
• Completion rates
• Recent activity tracking
• Enrollment trends

2. Student Analytics (Future)

• Engagement scoring
• Risk prediction (dropout risk)
• Performance trends
• Time-to-completion estimates

3. AI Recommendations (Future)

• Course recommendations based on progress
• Learning path suggestions
• Intervention alerts for at-risk students

4. Audit Logging

All actions are logged with:

• User ID
• Action type
• Resource affected
• Timestamp
• IP address
• Details

---

🔒 Security Features

Authentication

• JWT tokens with configurable expiration
• Refresh tokens for extended sessions
• Password hashing using bcrypt
• Session tracking with device info

Authorization

• Fine-grained RBAC with permission checking
• Hierarchical role management
• Resource-level access control
• Tool-permission mapping

Audit & Monitoring

• Comprehensive audit logs for all actions
• Session management with tracking
• Failed login detection
• Permission denial logging

---

📊 Database Schema

Core Tables

• users - User accounts
• roles - Role definitions
• permissions - Permission definitions
• user_roles - User-role assignments (many-to-many)
• role_permissions - Role-permission assignments (many-to-many)

LMS Tables

• courses - Course catalog
• course_modules - Course content structure
• students - Student profiles
• enrollments - Course enrollments
• module_progress - Detailed progress tracking

Security & Intelligence

• audit_logs - Action audit trail
• user_sessions - Active sessions
• student_analytics - AI-generated insights
• recommendations - Personalized recommendations

MCP Integration

• tool_registry - Available MCP tools
• tool_permissions - Tool-permission mapping

---

🚢 Deployment

Production Checklist

1. Environment Variables

DATABASE_URL=postgresql://user:pass@host/db  # Use PostgreSQL in production
JWT_SECRET_KEY=<strong-random-key>
ENVIRONMENT=production
ALLOWED_ORIGINS=https://yourdomain.com

2. Database Migration

• Switch from SQLite to PostgreSQL
• Set up connection pooling
• Enable WAL mode for better concurrency

3. Security Hardening

• Enable HTTPS
• Configure CORS properly
• Set up rate limiting
• Enable SQL injection protection
• Implement CSRF protection

4. Backend Deployment

# Using Docker
docker build -t lms-backend .
docker run -p 8000:8000 --env-file .env lms-backend

# Using systemd
sudo systemctl start lms-backend.service

5. Frontend Deployment

# Build production bundle
npm run build

# Serve with nginx or similar
cp -r dist/* /var/www/html/

6. Monitoring

• Set up error tracking (Sentry)
• Enable performance monitoring
• Configure log aggregation
• Set up health checks

---

🧪 Testing

Backend Tests

cd backend
pytest tests/

Frontend Tests

cd frontend
npm test

Integration Tests

# Test API endpoints
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password123"}'

---

📈 Future Enhancements

Phase 1 (Current)

• ✅ Advanced RBAC
• ✅ JWT Authentication
• ✅ Basic analytics
• ✅ Course management
• ✅ Enrollment tracking

Phase 2 (Next)

• AI-powered recommendations
• Student risk prediction
• Automated interventions
• Advanced analytics dashboard
• Email notifications

Phase 3 (Future)

• Video integration
• Live classes
• Discussion forums
• Certificate generation
• Payment integration
• Mobile app

---

🐛 Troubleshooting

Backend won't start

• Check Python version (3.9+)
• Verify all dependencies installed
• Check database file exists
• Review .env configuration

Frontend can't connect to backend

• Verify backend is running on port 8000
• Check CORS settings in main.py
• Ensure API_URL in App.jsx is correct

Permission denied errors

• Check user roles in database
• Verify role-permission mappings
• Review audit logs for details
• Ensure token is valid

Database errors

• Check database file permissions
• Verify schema is initialized
• Run seed data script
• Check for locked database

---

📞 Support

For issues or questions:

1. Check audit logs: SELECT * FROM audit_logs ORDER BY timestamp DESC LIMIT 50;
2. Review user permissions: Run RBAC queries
3. Check session status in user_sessions table
4. Review error logs in backend console

---

📝 License

This is an enterprise LMS system built for educational purposes.

---

🙏 Credits

Built with:

• FastAPI (Backend framework)
• React (Frontend framework)
• SQLite/PostgreSQL (Database)
• MCP Protocol (AI integration)
• JWT (Authentication)