229 lines
8.5 KiB
Markdown
229 lines
8.5 KiB
Markdown
# OpenCCB - Open Comprehensive Course Backbone
|
|
|
|
OpenCCB is a high-performance, microservices-based Learning Management System (LMS) and Content Management System (CMS) built with Rust (Edition 2024) and Next.js. The name stands for **Open Comprehensive Course Backbone**, representing the solid foundation for modern educational platforms.
|
|
|
|
## Architecture
|
|
|
|
- **CMS Service (Port 3001)**: Course management, content creation, grading policies, and administrative configurations.
|
|
- **LMS Service (Port 3002)**: Student experience, course consumption, enrollment, and grade tracking.
|
|
- **Shared Library**: Core models, authentication logic, and cross-service data contracts.
|
|
- **Database**: PostgreSQL with separate databases for CMS and LMS.
|
|
- **Studio (Frontend)**: Next.js application for instructors with block-based Activity Builder.
|
|
- **Experience (Frontend)**: Next.js student portal with interactive lesson player and progress dashboard.
|
|
- **Asset Storage**: Persistent local storage for native video/audio uploads.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Docker & Docker Compose
|
|
- Rust (Edition 2024)
|
|
- Node.js (v18+)
|
|
|
|
### Running with Docker
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### Access Points
|
|
- **Studio (Instructors)**: http://localhost:3000
|
|
- **Experience (Students)**: http://localhost:3003
|
|
- **CMS API**: http://localhost:3001
|
|
- **LMS API**: http://localhost:3002
|
|
|
|
## Core Features
|
|
|
|
### 🎨 Content Creation & Management
|
|
- **Block-Based Activity Builder**: Create rich lessons using text, media, and interactive assessment blocks
|
|
- **Advanced Assessment Types**:
|
|
- Multiple Choice & True/False
|
|
- Fill-in-the-Blanks
|
|
- Matching Pairs
|
|
- Ordering/Sequencing
|
|
- Short Answer (with configurable correct answers)
|
|
- **Native File Uploads**: Drag-and-drop video/audio uploads with persistent storage
|
|
- **Playback Constraints**: Limit media views per student
|
|
- **Dynamic Content Reordering**: Organize blocks with move up/down controls
|
|
- **Course Settings**: Configure passing percentages and grading criteria
|
|
|
|
### 📊 Advanced Grading System
|
|
- **Holistic Grading Policy**:
|
|
- Create weighted grading categories (e.g., Homework 30%, Exams 70%)
|
|
- Drop lowest N scores per category
|
|
- Automatic weighted grade calculation
|
|
- **Configurable Assessment Policies**:
|
|
- Set maximum attempts per lesson (1-10 or unlimited)
|
|
- Enable/disable instant corrections and retries
|
|
- Atomic attempt tracking with enforcement
|
|
- **Dynamic Passing Thresholds**:
|
|
- Instructors set custom passing percentages (0-100%)
|
|
- 5-tier performance visualization for students:
|
|
- **Reprobado (Red)**: 0% to P-1%
|
|
- **Rendimiento Bajo (Orange)**: P% to P+9%
|
|
- **Rendimiento Medio (Yellow)**: P+10% to P+15%
|
|
- **Buen Rendimiento (Green)**: P+16% to 90%
|
|
- **Excelente (Blue)**: 91%+
|
|
|
|
### 📈 Analytics & Insights
|
|
- **Instructor Analytics Dashboard**:
|
|
- Total enrollments per course
|
|
- Overall average score across all assessments
|
|
- Per-lesson performance breakdown
|
|
- Automatic detection of "struggling lessons" (avg score < 70%)
|
|
- Visual performance charts
|
|
- **Student Progress Dashboard**:
|
|
- Real-time weighted grade calculation
|
|
- Category-by-category breakdown
|
|
- Interactive performance bar with tier visualization
|
|
- Lesson completion tracking
|
|
|
|
### 🔐 Authentication & Security
|
|
- **JWT-Based Authentication**: Secure token-based auth across all services
|
|
- **Role-Based Access Control (RBAC)**:
|
|
- **Administrators**: Full platform access, global analytics, all course management
|
|
- **Instructors**: Course creation, analytics for assigned courses only
|
|
- **Students**: Course enrollment, lesson consumption, progress tracking
|
|
- **Service-to-Service Authorization**: Secure internal API calls with token validation
|
|
- **Audit Logging**: All CMS mutations recorded for compliance and debugging
|
|
|
|
### 🚀 Service Integration
|
|
- **Automatic Sync**: One-click publish from CMS to LMS
|
|
- **Cross-Service Data Flow**: Courses, modules, lessons, and grading policies synchronized
|
|
- **Real-Time Updates**: Student progress immediately reflected in analytics
|
|
|
|
## API Documentation
|
|
|
|
### CMS Service (`:3001`)
|
|
|
|
#### Authentication
|
|
```bash
|
|
# Register (Instructor/Admin)
|
|
curl -X POST http://localhost:3001/auth/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"email": "instructor@example.com", "password": "secure123", "full_name": "John Doe", "role": "instructor"}'
|
|
|
|
# Login
|
|
curl -X POST http://localhost:3001/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"email": "instructor@example.com", "password": "secure123"}'
|
|
```
|
|
|
|
#### Course Management
|
|
```bash
|
|
# Create Course
|
|
curl -X POST http://localhost:3001/courses \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"title": "Advanced Rust 2024"}'
|
|
|
|
# Update Course Settings
|
|
curl -X PUT http://localhost:3001/courses/{id} \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer YOUR_TOKEN" \
|
|
-d '{"passing_percentage": 75}'
|
|
|
|
# Publish Course to LMS
|
|
curl -X POST http://localhost:3001/courses/{id}/publish \
|
|
-H "Authorization: Bearer YOUR_TOKEN"
|
|
|
|
# Get Course Analytics (RBAC enforced)
|
|
curl http://localhost:3001/courses/{id}/analytics \
|
|
-H "Authorization: Bearer YOUR_TOKEN"
|
|
```
|
|
|
|
### LMS Service (`:3002`)
|
|
|
|
#### Student Operations
|
|
```bash
|
|
# Register Student
|
|
curl -X POST http://localhost:3002/auth/register \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"email": "student@example.com", "password": "secure123", "full_name": "Jane Smith"}'
|
|
|
|
# Get Course Catalog
|
|
curl http://localhost:3002/catalog
|
|
|
|
# Enroll in Course
|
|
curl -X POST http://localhost:3002/enroll \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"user_id": "USER_UUID", "course_id": "COURSE_UUID"}'
|
|
|
|
# Submit Lesson Score
|
|
curl -X POST http://localhost:3002/grades \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"user_id": "USER_UUID", "lesson_id": "LESSON_UUID", "score": 0.85}'
|
|
|
|
# Get Student Grades
|
|
curl http://localhost:3002/users/{user_id}/courses/{course_id}/grades
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
### Backend
|
|
- **Rust 2024**: High-performance, memory-safe backend services
|
|
- **Axum 0.8**: Modern async web framework
|
|
- **SQLx**: Compile-time verified SQL queries
|
|
- **PostgreSQL**: Robust relational database
|
|
- **JWT**: Secure authentication tokens
|
|
|
|
### Frontend
|
|
- **Next.js 14**: React framework with App Router
|
|
- **TypeScript**: Type-safe frontend development
|
|
- **Tailwind CSS**: Utility-first styling
|
|
- **Lucide React**: Modern icon library
|
|
|
|
### DevOps
|
|
- **Docker**: Containerized deployment
|
|
- **Docker Compose**: Multi-service orchestration
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
openccb/
|
|
├── services/
|
|
│ ├── cms-service/ # Course management backend
|
|
│ │ ├── src/
|
|
│ │ │ ├── handlers.rs # API handlers
|
|
│ │ │ └── main.rs # Service entry point
|
|
│ │ └── migrations/ # Database migrations
|
|
│ └── lms-service/ # Learning management backend
|
|
│ ├── src/
|
|
│ │ ├── handlers.rs # API handlers
|
|
│ │ └── main.rs # Service entry point
|
|
│ └── migrations/ # Database migrations
|
|
├── shared/
|
|
│ └── common/ # Shared models and auth
|
|
│ └── src/
|
|
│ ├── models.rs # Data models
|
|
│ └── auth.rs # JWT utilities
|
|
├── web/
|
|
│ ├── studio/ # Instructor frontend
|
|
│ │ └── src/
|
|
│ │ ├── app/ # Next.js pages
|
|
│ │ ├── components/ # React components
|
|
│ │ └── lib/ # API client
|
|
│ └── experience/ # Student frontend
|
|
│ └── src/
|
|
│ ├── app/ # Next.js pages
|
|
│ ├── components/ # React components
|
|
│ └── lib/ # API client
|
|
└── docker-compose.yml # Service orchestration
|
|
```
|
|
|
|
## Recent Enhancements
|
|
|
|
### December 2024
|
|
- ✅ **Holistic Grading System**: Weighted categories, drop policies, and automatic calculation
|
|
- ✅ **Attempt Tracking**: Configurable max attempts and retry policies per lesson
|
|
- ✅ **Instructor Analytics**: Course-level insights with RBAC enforcement
|
|
- ✅ **Dynamic Passing Thresholds**: Customizable pass marks with 5-tier performance visualization
|
|
- ✅ **Role-Based Access Control**: Admin, Instructor, and Student roles with granular permissions
|
|
- ✅ **Enhanced Progress Dashboard**: Real-time weighted grades and visual performance bars
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please ensure all tests pass and follow the existing code style.
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|