Nurfog/openccb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement comprehensive course analytics, RBAC with roles and authentication, and dynamic passing thresholds.

Browse Source
This commit is contained in:
Juan Enrique Allende Cifuentes
2025-12-23 10:12:53 -03:00
parent f592f78b6c
commit 72ddb43fd7
29 changed files with 1433 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+186 -48
View File
@@ -4,11 +4,12 @@ OpenCCB is a high-performance, microservices-based Learning Management System (L
## Architecture
- **CMS Service (Port 3001)**: Course management, content creation, and administrative configurations.
- **LMS Service (Port 3002)**: Student experience, course consumption, and enrollment.
- **Shared Library**: Core models and authentication logic.
- **Database**: PostgreSQL (shared/isolated schemas).
- **Studio (Frontend)**: Next.js application with a block-based **Activity Builder** for instructors.
- **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
@@ -24,67 +25,204 @@ OpenCCB is a high-performance, microservices-based Learning Management System (L
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`)
#### Create a Course
- **URL**: `/courses`
- **Method**: `POST`
- **Example**:
#### 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"}'
```
- **Response**:
```json
{
"id": "uuid-v4",
"title": "Advanced Rust 2024",
"description": null,
"instructor_id": "uuid-v4",
"start_date": null,
"end_date": null,
"created_at": "2023-12-19T10:00:00Z",
"updated_at": "2023-12-19T10:00:00Z"
}
```
#### Create a Module
- **URL**: `/modules`
- **Method**: `POST`
- **Example**:
```bash
curl -X POST http://localhost:3001/modules \
# Update Course Settings
curl -X PUT http://localhost:3001/courses/{id} \
-H "Content-Type: application/json" \
-d '{"title": "Introduction", "course_id": "YOUR_COURSE_ID", "position": 1}'
-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`)
#### Get Course Catalog
- **URL**: `/catalog`
- **Method**: `GET`
- **Example**:
#### Student Operations
```bash
curl http://localhost:3002/catalog
```
# 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"}'
#### Enroll in a Course
- **URL**: `/enroll`
- **Method**: `POST`
- **Example**:
```bash
# Get Course Catalog
curl http://localhost:3002/catalog
# Enroll in Course
curl -X POST http://localhost:3002/enroll \
-H "Content-Type: application/json" \
-d '{"course_id": "YOUR_COURSE_ID"}'
-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
```
Every mutation in the CMS (Create Course/Module/Lesson) is automatically recorded in the `audit_logs` table for compliance and debugging.
## Technology Stack
## Features
- **Block-Based Activity Builder**: Create lessons using text, media, and interactive quiz blocks.
- **Native File Uploads**: Drag-and-drop video/audio uploads with persistence.
- **Playback Constraints**: Limit how many times students can view specific media items.
- **Dynamic Reordering**: (Coming Soon) Organize content blocks with a single click.
### 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.