courseworx/docs/01-System-Architecture.md

CourseWorx System Architecture Documentation

📋 Document Information

• Version: 1.0.0
• Last Updated: 2024-12-19
• Author: AI Assistant
• Status: Draft - Ready for Review

🎯 Executive Summary

CourseWorx is a comprehensive Learning Management System (LMS) built with a modern full-stack architecture. The system supports three user roles (Super Admin, Trainer, Trainee) and provides comprehensive course management, content delivery, and learning tracking capabilities.

🏗️ System Overview

Architecture Pattern

• Frontend: Single Page Application (SPA) with React
• Backend: RESTful API with Express.js
• Database: PostgreSQL with Sequelize ORM
• Authentication: JWT-based with role-based access control
• File Storage: Local file system with organized uploads

Technology Stack

Frontend Layer:
├── React 18 (UI Framework)
├── React Router (Routing)
├── React Query (State Management)
├── Tailwind CSS (Styling)
├── Heroicons (Icon System)
└── Axios (HTTP Client)

Backend Layer:
├── Node.js (Runtime)
├── Express.js (Web Framework)
├── Sequelize (ORM)
├── JWT (Authentication)
├── bcryptjs (Security)
└── Multer (File Uploads)

Data Layer:
├── PostgreSQL (Primary Database)
├── Sequelize Models (Data Models)
└── File System (Content Storage)

🔐 Security Architecture

Authentication Flow

1. Login: User credentials → bcrypt validation → JWT token generation
2. Authorization: JWT token → Role verification → Route access control
3. Session Management: Token expiration → Automatic logout → Secure storage

Role-Based Access Control (RBAC)

Super Admin:
├── Full system access
├── User management
├── Course oversight
└── System configuration

Trainer:
├── Course creation/management
├── Student management
├── Content management
└── Progress tracking

Trainee:
├── Course enrollment
├── Content consumption
├── Progress tracking
└── Assignment submission

📊 Data Flow Architecture

User Journey Flow

1. Authentication → JWT Token Generation
2. Role Verification → Route Access Control
3. Data Request → API Validation → Database Query
4. Response Processing → Frontend State Update
5. UI Rendering → User Interaction

API Request Flow

Frontend → API Gateway → Route Handler → Middleware → Controller → Model → Database
Response: Database → Model → Controller → Middleware → Route Handler → API Gateway → Frontend

🗄️ Database Architecture

Database Schema Overview

• Users: Authentication, roles, profiles
• Courses: Course metadata, structure, settings
• CourseSections: Course organization units
• CourseContent: Learning materials, files, quizzes
• Enrollments: Student-course relationships
• LessonCompletion: Progress tracking
• Assignments: Task management
• Attendance: Session tracking
• UserNotes: Personal annotations

Data Relationships

User (1) ←→ (Many) Course (as Trainer)
User (1) ←→ (Many) Enrollment (as Trainee)
Course (1) ←→ (Many) CourseSection
CourseSection (1) ←→ (Many) CourseContent
Course (1) ←→ (Many) CourseContent
User (1) ←→ (Many) LessonCompletion
CourseContent (1) ←→ (Many) LessonCompletion

🚀 Performance Architecture

Caching Strategy

• Frontend: React Query for API response caching
• Backend: No current caching implementation
• Database: PostgreSQL query optimization

Scalability Considerations

• Horizontal Scaling: Stateless API design
• Database Scaling: Connection pooling, query optimization
• File Storage: Organized directory structure for scalability

🔧 Configuration Management

Environment Variables

Server Configuration:
├── PORT (Server port)
├── NODE_ENV (Environment)
└── CORS_ORIGIN (Allowed origins)

Database Configuration:
├── DB_HOST (Database host)
├── DB_PORT (Database port)
├── DB_NAME (Database name)
├── DB_USER (Database user)
└── DB_PASSWORD (Database password)

Security Configuration:
├── JWT_SECRET (JWT signing key)
└── JWT_EXPIRES_IN (Token expiration)

📱 Frontend Architecture

Component Structure

App.js
├── AuthProvider (Context)
├── Routes
│   ├── Public Routes
│   └── Private Routes
│       ├── Layout Component
│       └── Page Components
└── Global State Management

State Management

• React Context: Authentication state
• React Query: Server state management
• Local State: Component-specific state
• URL State: Route parameters and query strings

🔌 Backend Architecture

API Structure

/api
├── /auth (Authentication)
├── /users (User management)
├── /courses (Course management)
├── /course-content (Content management)
├── /course-sections (Section management)
├── /enrollments (Enrollment management)
├── /attendance (Attendance tracking)
├── /assignments (Assignment management)
├── /lesson-completion (Progress tracking)
├── /course-stats (Statistics)
└── /user-notes (Personal notes)

Middleware Stack

Request → CORS → Helmet → JSON Parser → Route Handler → Error Handler → Response

🚨 Critical Issues Identified

1. Large Components

• CourseContent.js: 1736 lines - Needs immediate refactoring
• CourseContentViewer.js: 835 lines - Should be split
• Users.js: 496 lines - Mixed concerns

2. No Testing Infrastructure

• Unit Tests: Not implemented
• Integration Tests: Not implemented
• API Tests: Not implemented
• End-to-End Tests: Not implemented

3. Documentation Gaps

• API Documentation: Incomplete
• Component Documentation: Missing
• Development Guidelines: Not established

4. Security Concerns

• Input Validation: Inconsistent implementation
• File Upload Security: Basic validation only
• Error Handling: Exposes internal details

🔮 Future Architecture Considerations

Planned Improvements

1. Microservices: Break down monolithic API
2. Message Queue: Async processing for file uploads
3. CDN Integration: Content delivery optimization
4. Real-time Features: WebSocket for live updates
5. Mobile App: React Native or Flutter

Technical Debt

1. Large Components: Immediate refactoring needed
2. Testing Infrastructure: Critical missing piece
3. Documentation: Limited technical documentation
4. Code Quality: Mixed concerns in components

---

Next Steps:

1. Review and validate this architecture document
2. Create detailed API documentation
3. Establish testing infrastructure
4. Implement development workflow improvements