# System Architecture Documentation

## 1. System Overview

### What Problem This CMS Solves

This Laravel-based Content Management System (CMS) serves as a management and orchestration layer for a Learning Management System (LMS) built on Moodle. The system addresses the need for:

- **Centralized Content Management**: Providing a user-friendly interface for administrators, teachers, and content editors to create, organize, and manage educational content without directly interacting with Moodle's complex interface.

- **Multi-Tenant Support**: Enabling multiple organizations (tenants) to operate independently within the same system, each with their own database and configuration.

- **User & Enrollment Management**: Streamlining the creation and management of users (students, teachers, administrators) and their course enrollments across multiple tenants.

- **Content Synchronization**: Automatically synchronizing course structures, activities, quizzes, and learning materials between the CMS and Moodle LMS.

- **Assessment & Grading**: Managing exams, quizzes, rubrics, and student performance tracking with integration to Moodle's assessment capabilities.

### Who Uses It

- **Administrators**: Manage system configuration, tenants, users, roles, and permissions
- **Teachers**: Create courses, design activities, manage classes, grade assignments, and track student progress
- **Content Editors**: Create and organize learning materials, quizzes, and multimedia content
- **Students**: Access courses and learning materials (primarily through Moodle, but enrollment is managed via CMS)
- **System Integrators**: API consumers for third-party integrations (e.g., Speakup, Zeus, ICANID)

### What Laravel CMS is Responsible For

The Laravel CMS acts as the **management and orchestration layer**, responsible for:

- **Content Authoring & Organization**: Course structure, sections, activities (quizzes, assignments, resources)
- **User Management**: User accounts, roles, permissions, multi-tenant user assignments
- **Enrollment Management**: Student-course associations, class management, teacher assignments
- **Business Logic**: Activity completion tracking, progress monitoring, assessment workflows
- **Data Synchronization**: Pushing course structures and activities to Moodle via REST API
- **Multi-Tenant Orchestration**: Managing separate databases and configurations per tenant
- **File Management**: Uploading and managing media files (images, videos) via AWS S3
- **Notification System**: Real-time notifications via Pusher/Soketi

**Moodle LMS** serves as the **content storage and delivery layer**, responsible for:

- **Actual Learning Content Storage**: Storing course content, activities, and student submissions
- **Student Learning Interface**: Providing the actual learning environment where students access courses
- **Assessment Execution**: Running quizzes, collecting student answers, calculating grades
- **Completion Tracking**: Tracking student progress through activities and courses
- **Gradebook**: Storing and calculating student grades and performance data

---

## 2. High-level Architecture

### Overall Architecture Description

The system follows a **hybrid architecture** combining:

1. **Laravel CMS (Management Layer)**: Monolithic Laravel application handling business logic, content management, and user interfaces
2. **Moodle LMS (Content Storage & Delivery Layer)**: External Moodle instance providing learning content storage and student-facing interfaces
3. **Multi-Tenant Database Architecture**: Separate databases per tenant with dynamic connection management
4. **Queue-Based Processing**: Asynchronous job processing for heavy operations (enrollments, imports, syncs)
5. **Cloud Storage**: AWS S3 for media file storage
6. **Real-time Communication**: Pusher/Soketi for notifications

### Technologies Used

- **Framework**: Laravel 11.x (PHP 8.2+)
- **Database**: MySQL (multiple databases: master + per-tenant)
- **Cache**: Laravel's default cache (configurable: Redis, database, file)
- **Queue**: Database queue driver (configurable: Redis, SQS, Beanstalkd)
- **Storage**: 
  - Local filesystem for temporary files
  - AWS S3 for media files (images, videos)
- **Authentication**: 
  - Laravel Sanctum for API authentication
  - Keycloak/ICANID for SSO integration
  - Google OAuth for social login
- **Real-time**: Pusher/Soketi for WebSocket notifications
- **External Services**:
  - Moodle LMS (REST API)
  - AWS S3
  - OpenAI/Gemini for AI features
  - Sentry for error tracking

### External Systems

- **Moodle LMS**: Primary external system for content storage and delivery
  - Communication: REST API (via `config/services.lms.URL_API_LMS`)
  - Authentication: Token-based (`config/services.lms.TOKEN_LMS`)
  - Database: Separate Moodle database (optional direct access via `config/database.php` moodle connection)

### Architecture Diagram

```mermaid
graph TD
    User[Users<br/>Admin/Teacher/Student] --> CMS[Laravel CMS<br/>Management Layer]
    
    CMS --> MasterDB[(Master Database<br/>Users, Tenants, Config)]
    CMS --> TenantDB1[(Tenant DB 1<br/>ICC)]
    CMS --> TenantDB2[(Tenant DB 2<br/>OMO)]
    CMS --> TenantDB3[(Tenant DB N<br/>...)]
    
    CMS --> Moodle[Moodle LMS<br/>Content Storage & Delivery]
    CMS --> S3[AWS S3<br/>Media Files]
    CMS --> Queue[Queue System<br/>Async Jobs]
    CMS --> Cache[Cache Layer]
    CMS --> Notifications[Pusher/Soketi<br/>Real-time Notifications]
    
    Moodle --> MoodleDB[(Moodle Database<br/>Content & Grades)]
    
    Student[Students] --> Moodle
    Student --> MoodleDB
    
    CMS --> Keycloak[Keycloak/ICANID<br/>SSO]
    CMS --> OpenAI[OpenAI/Gemini<br/>AI Services]
    
    style CMS fill:#e1f5ff
    style Moodle fill:#fff4e1
    style MasterDB fill:#e8f5e9
    style TenantDB1 fill:#e8f5e9
    style TenantDB2 fill:#e8f5e9
    style TenantDB3 fill:#e8f5e9
    style MoodleDB fill:#fff4e1
```

---

## 3. Folder & Code Structure

### Important Folders

#### `app/`
Core application logic organized by responsibility:

- **`app/Http/Controllers/`**: HTTP request handlers
  - `CourseController.php`: Course management
  - `ProductController.php`: Content/product management (courses, sections, activities)
  - `StudentController.php`: Student management
  - `TeacherController.php`: Teacher management
  - `ApiMoodleController.php`: Moodle integration endpoints
  - `Auth/`: Authentication controllers

- **`app/Models/`**: Eloquent ORM models
  - `ApiMoodle.php`: Represents Moodle entities (courses, sections, quizzes, activities)
  - `Course.php`: CMS course representation
  - `Students.php`: Student records
  - `Teachers.php`: Teacher records
  - `Classes.php`: Class/group management
  - `User.php`: System users (admins, content editors)
  - `Roles.php`, `Permission.php`: RBAC system
  - `HocmaiTenant.php`: Multi-tenant configuration

- **`app/Services/`**: Business logic layer
  - `ApiMoodleService.php`: Moodle integration service
  - `CourseService.php`: Course business logic
  - `ActivityProgressService.php`: Activity completion tracking

- **`app/ApiService/`**: External API integration services
  - `FeService.php`: Frontend service layer (Moodle API wrapper, user creation, enrollment)

- **`app/Jobs/`**: Queue jobs for asynchronous processing
  - `ProcessStudentCreationJob.php`: Async student creation
  - `ProcessStudentEnrollmentRequestJob.php`: Async enrollment processing
  - `ActivityCompletionSyncJob.php`: Sync activity completions to Moodle
  - `ImportEmsQuestionsJob.php`: Bulk question import

- **`app/Helpers/`**: Utility functions
  - `Helper.php`: General helper functions (permissions, validation)
  - `HelperTenant.php`: Multi-tenant utilities

- **`app/Observers/`**: Model event observers
  - `ApiMoodleObserver.php`: Auto-creates `Course` records when `ApiMoodle` course is created

- **`app/Modules/`**: Modular features
  - `UiBuilder/`: UI template builder module

#### `routes/`
Route definitions:

- **`web.php`**: Web routes (admin panel, content management)
- **`api.php`**: API routes (REST endpoints for integrations)
- **`console.php`**: Scheduled task definitions (cron jobs)

#### `database/`
Database schema and seeders:

- **`migrations/`**: Database schema migrations
  - User management tables
  - Multi-tenant tables (`hocmai_tenants`, `user_tenants`)
  - Course/content tables (`api_moodle`, `courses`, `sections`)
  - Student/teacher tables (`students`, `teachers`, `classes`)
  - RBAC tables (`roles`, `permissions`, `role_permission`, `user_role`)
  - Activity tracking tables (`student_activity_progress`, `activity_completion_activities`)

- **`seeders/`**: Database seeders for initial data

#### `config/`
Configuration files:

- **`services.php`**: External service configurations (Moodle, Keycloak, AWS)
- **`database.php`**: Database connections (master, tenant connections, Moodle)
- **`filesystems.php`**: Storage disk configurations (local, S3)
- **`queue.php`**: Queue driver configuration
- **`auth.php`**: Authentication configuration

### How Responsibilities are Separated

1. **Controllers**: Handle HTTP requests, validate input, call services, return responses
2. **Services**: Contain business logic, orchestrate multiple models/repositories
3. **Models**: Data access layer, relationships, scopes
4. **Repositories**: Data access abstraction (using `prettus/l5-repository`)
5. **Jobs**: Asynchronous processing for heavy operations
6. **Helpers**: Reusable utility functions
7. **Observers**: Side effects when models are created/updated/deleted

---

## 4. Core Modules

### Authentication & Authorization

**Purpose**: Manage user authentication and access control

**Key Models**:
- `User`: System users (admins, content editors)
- `Roles`: User roles (admin, teacher, content_editor, etc.)
- `Permission`: Route-based permissions
- `RolePermission`: Many-to-many relationship between roles and permissions
- `UserRole`: Many-to-many relationship between users and roles

**Key Controllers/Services**:
- `Auth/AuthenticatedSessionController`: Login/logout
- `AuthSSOController`: SSO integration (Keycloak, ICANID)
- `GoogleController`: Google OAuth login
- `Helper::checkPermissionUser()`: Permission checking middleware

**Important Relationships**:
- User → UserRole → Role → RolePermission → Permission
- Admin role bypasses permission checks
- Multi-tenant users have separate role assignments per tenant

**Authentication Methods**:
- Standard Laravel authentication (email/password)
- Keycloak SSO
- ICANID SSO
- Google OAuth

### User Management

**Purpose**: Manage system users, teachers, and students

**Key Models**:
- `User`: CMS users (admins, content editors)
- `Teachers`: Teacher records (linked to `User`)
- `Students`: Student records (can have `user_id` or standalone)
- `HocmaiTenant`: Tenant/organization definitions
- `UserTenant`: Many-to-many relationship between users and tenants

**Key Controllers**:
- `UserController`: User CRUD operations
- `TeacherController`: Teacher management
- `StudentController`: Student management
- `TenantController`: Tenant selection and switching

**Important Relationships**:
- `User` has one `Teachers` (optional)
- `Students` can belong to multiple `Classes`
- `Students` can be enrolled in multiple `Courses` (via `course_student`)
- Users can belong to multiple tenants (via `user_tenants`)

**Features**:
- Multi-tenant user assignment
- Automatic Moodle user creation when students/teachers are created
- SSO integration for user provisioning

### Course / Content Management

**Purpose**: Create, organize, and manage courses, sections, and learning activities

**Key Models**:
- `ApiMoodle`: Represents Moodle entities (courses, sections, quizzes, assignments, resources, URLs, H5P tools)
  - `moodle_type`: 'course', 'section', 'quiz', 'assign', 'resource', 'url', 'cm_h5p_tool'
  - `moodle_id`: ID in Moodle system
  - `parent_id`: Hierarchical structure (section → course, activity → section)
- `Course`: CMS representation of courses (linked to `ApiMoodle`)
- `LmsCourse`: Legacy course table
- `LmsSection`: Legacy section table

**Key Controllers**:
- `ProductController`: Main content management (courses, sections, activities)
- `CourseController`: Course-level operations
- `ApiMoodleController`: Moodle entity management

**Key Services**:
- `ApiMoodleService`: Moodle entity business logic
- `CourseService`: Course management logic
- `FeService`: Moodle API wrapper methods

**Important Relationships**:
- `Course` belongs to `ApiMoodle` (via `api_moodle_id`)
- `ApiMoodle` has hierarchical structure via `parent_id`
- Activities (quiz, assign, resource) belong to sections
- Sections belong to courses

**Content Types**:
- **Courses**: Top-level containers
- **Sections**: Course sections/chapters
- **Quizzes**: Assessment activities with questions
- **Assignments**: Submission-based activities
- **Resources**: File downloads
- **URLs**: External links
- **H5P Tools**: Interactive content (videos, presentations)

**Sync Strategy**:
- When content is created/updated in CMS, it's immediately synced to Moodle via REST API
- `ApiMoodle` table stores the mapping between CMS IDs and Moodle IDs
- Observer pattern: `ApiMoodleObserver` auto-creates `Course` records when courses are created

### Moodle Integration Module

**Purpose**: Synchronize content and data between Laravel CMS and Moodle LMS

**Key Components**:
- **`app/Models/Common.php`**: Moodle REST API wrapper methods
  - `core_course_create_courses()`: Create courses in Moodle
  - `core_course_get_courses()`: Fetch courses from Moodle
  - `local_custom_service_create_activity_quiz()`: Create quiz activities
  - `local_custom_service_update_activity_quiz()`: Update quiz settings
  - `core_user_create_users()`: Create users in Moodle
  - `core_user_get_users_by_field()`: Find users in Moodle
  - `core_enrol_get_users_courses()`: Get user enrollments
  - Many more Moodle API methods

- **`app/ApiService/FeService.php`**: High-level Moodle operations
  - `createUserMoodle()`: Create user with proper encoding and error handling
  - `enrollStudentWithCourseHandling()`: Enroll students in courses
  - `enrollTeacherWithCourseHandling()`: Enroll teachers in courses

- **`app/Jobs/ActivityCompletionSyncJob.php`**: Sync activity completions from Moodle to CMS

**Data Flow**:
1. **Content Creation**: CMS → Moodle API → Moodle stores content
2. **User Creation**: CMS → Moodle API → Moodle creates user account
3. **Enrollment**: CMS → Moodle API → Moodle enrolls user in course
4. **Completion Tracking**: Moodle → CMS (via sync jobs/webhooks)

**Authentication with Moodle**:
- Token-based authentication via `config/services.lms.TOKEN_LMS`
- API endpoint: `config/services.lms.URL_API_LMS`
- All requests include authentication token in headers

**What Data is Stored Where**:

| Data Type | Laravel CMS | Moodle LMS |
|-----------|-------------|------------|
| Course structure (sections, activities) | ✅ Metadata, hierarchy | ✅ Actual content |
| Student submissions | ❌ | ✅ |
| Grades | ✅ Aggregated data | ✅ Detailed grades |
| User accounts | ✅ Management data | ✅ Login credentials |
| Course enrollments | ✅ Relationships | ✅ Active enrollments |
| Activity completions | ✅ Tracking | ✅ Source of truth |
| Media files | ✅ Metadata | ✅ Referenced in content |

### Multi-Tenant Architecture

**Purpose**: Support multiple organizations (tenants) with isolated data

**Key Models**:
- `HocmaiTenant`: Tenant definitions (code, name, db_name, status)
- `HocmaiTenantDomain`: Domain-to-tenant mapping
- `UserTenant`: User-tenant assignments

**Key Helpers**:
- `HelperTenant`: Tenant management utilities
  - `getCurrentTenantConnection()`: Get current tenant DB connection
  - `setupTenantConnection()`: Dynamically configure tenant database connection
  - `getUserTenants()`: Get all tenants for a user

**Architecture**:
- **Master Database**: Stores users, tenants, global configuration
- **Tenant Databases**: Separate database per tenant (e.g., `lmsnew_hocmai_icc`, `lmsnew_hocmai_omo`)
- **Dynamic Connections**: Tenant connections are configured at runtime based on domain or user selection
- **Model Trait**: `UsesTenantConnection` trait allows models to use tenant connections

**Tenant Selection**:
- Users can belong to multiple tenants
- Tenant selection via domain (automatic) or user selection (manual)
- Session-based tenant context

### Assessment & Grading

**Purpose**: Manage exams, quizzes, rubrics, and student performance

**Key Models**:
- `ApiMoodle`: Quiz activities (when `moodle_type = 'quiz'`)
- `ApiEms`: EMS (Exam Management System) activities
- `RubricTemplate`: Rubric templates for grading
- `RubricScore`: Rubric scores for assignments
- `StudentScore`: Student performance scores
- `StudentExamHistory`: Exam attempt history
- `EmsQuestion`: EMS questions
- `EmsType`: EMS activity types

**Key Controllers**:
- `EmsExamController`: EMS exam management
- `RubricTemplateController`: Rubric management
- `StudentExamHistoryController`: Exam history tracking

**Features**:
- Quiz templates (default, kidbox)
- Rubric-based grading
- Component-based scoring (listening, reading, writing, speaking)
- Attempt tracking and limits
- Penalty calculations for wrong answers

### Notification System

**Purpose**: Real-time notifications for users

**Key Models**:
- `NotificationReceive`: Notification records
- `NotificationReceiveUser`: User-notification relationships

**Key Jobs**:
- `ProcessNotificationReceiveJob`: Process and send notifications

**Technology**:
- Pusher/Soketi for WebSocket real-time delivery
- Database queue for reliable delivery

---

## 5. Data Model

### Main Database Tables

#### Master Database Tables

**User Management**:
- `users`: System users (admins, content editors)
- `roles`: User roles
- `permissions`: Route-based permissions
- `role_permission`: Role-permission mapping
- `user_role`: User-role mapping

**Multi-Tenant**:
- `hocmai_tenants`: Tenant definitions
- `hocmai_tenant_domains`: Domain-to-tenant mapping
- `user_tenants`: User-tenant assignments

#### Tenant Database Tables (per tenant)

**Content Management**:
- `api_moodle`: Moodle entities (courses, sections, activities)
- `courses`: CMS course representation
- `lms_course`: Legacy course table
- `lms_section`: Legacy section table

**User Management**:
- `students`: Student records
- `teachers`: Teacher records
- `classes`: Class/group definitions
- `users`: Tenant-specific users (if applicable)

**Relationships**:
- `course_student`: Student-course enrollments
- `course_teacher`: Teacher-course assignments
- `class_course`: Class-course relationships
- `student_class`: Student-class memberships

**Assessment**:
- `api_ems`: EMS activities
- `ems_questions`: EMS questions
- `rubric_templates`: Rubric templates
- `rubric_scores`: Rubric scores
- `student_score`: Student performance scores
- `student_exam_history`: Exam attempt history

**Activity Tracking**:
- `student_activity_progress`: Activity completion tracking
- `activity_completion_activities`: Activity completion definitions
- `activity_condition_sets`: Activity prerequisites

**Other**:
- `s3_media_files`: S3 file metadata
- `notification_receives`: Notifications
- `ui_templates`: UI builder templates

### Key Relationships

#### One-to-Many (1-N)

- `HocmaiTenant` → `HocmaiTenantDomain` (one tenant has many domains)
- `ApiMoodle` (course) → `ApiMoodle` (sections) via `parent_id`
- `ApiMoodle` (section) → `ApiMoodle` (activities) via `parent_id`
- `Course` → `ApiMoodle` (via `api_moodle_id`)
- `Classes` → `ClassCourse` → `ApiMoodle` (courses)
- `Teachers` → `CourseTeacher` → `ApiMoodle` (courses)

#### Many-to-Many (N-N)

- `User` ↔ `Roles` (via `user_role`)
- `Roles` ↔ `Permissions` (via `role_permission`)
- `User` ↔ `HocmaiTenant` (via `user_tenants`)
- `Students` ↔ `ApiMoodle` (courses) via `course_student`
- `Teachers` ↔ `ApiMoodle` (courses) via `course_teacher`
- `Classes` ↔ `ApiMoodle` (courses) via `class_course`
- `Students` ↔ `Classes` via `student_class`

#### One-to-One (1-1)

- `User` → `Teachers` (optional, via `user_id`)

### Business Entities

1. **Tenant**: Organization (e.g., ICC, OMO)
2. **User**: System user (admin, content editor)
3. **Teacher**: Teacher account (linked to User or standalone)
4. **Student**: Student account
5. **Course**: Learning course (mapped to Moodle course)
6. **Section**: Course section/chapter
7. **Activity**: Learning activity (quiz, assignment, resource, URL, H5P)
8. **Class**: Student group/class
9. **Role**: User role (admin, teacher, etc.)
10. **Permission**: Route-based permission

### Entity Relationship Diagram

```mermaid
erDiagram
    HocmaiTenant ||--o{ HocmaiTenantDomain : "has"
    HocmaiTenant ||--o{ UserTenant : "has"
    User ||--o{ UserTenant : "belongs to"
    User ||--o{ UserRole : "has"
    UserRole }o--|| Roles : "references"
    Roles ||--o{ RolePermission : "has"
    RolePermission }o--|| Permission : "references"
    
    User ||--o| Teachers : "may have"
    
    ApiMoodle ||--o{ ApiMoodle : "parent_id (hierarchy)"
    ApiMoodle ||--|| Course : "maps to"
    
    Students ||--o{ CourseStudent : "enrolled in"
    CourseStudent }o--|| ApiMoodle : "references (course)"
    
    Teachers ||--o{ CourseTeacher : "teaches"
    CourseTeacher }o--|| ApiMoodle : "references (course)"
    
    Classes ||--o{ ClassCourse : "contains"
    ClassCourse }o--|| ApiMoodle : "references (course)"
    
    Students ||--o{ StudentClass : "belongs to"
    StudentClass }o--|| Classes : "references"
    
    ApiMoodle ||--o{ ApiEms : "has"
    ApiMoodle ||--o{ RubricTemplate : "uses"
    RubricTemplate ||--o{ RubricScore : "has"
    
    Students ||--o{ StudentScore : "has"
    Students ||--o{ StudentExamHistory : "has"
```

---

## 6. Main System Flows

### User Login Flow

```mermaid
sequenceDiagram
    participant User
    participant CMS
    participant Keycloak
    participant Moodle
    
    User->>CMS: Access /login
    CMS->>User: Show login form
    
    alt Standard Login
        User->>CMS: Submit email/password
        CMS->>CMS: Validate credentials
        CMS->>CMS: Check user roles/permissions
        CMS->>User: Redirect to dashboard
    else SSO Login (Keycloak/ICANID)
        User->>CMS: Click SSO login
        CMS->>Keycloak: Redirect to SSO
        Keycloak->>User: Authenticate
        Keycloak->>CMS: Return with token
        CMS->>CMS: Validate token, create/update user
        CMS->>User: Redirect to dashboard
    else Google OAuth
        User->>CMS: Click Google login
        CMS->>Google: OAuth flow
        Google->>CMS: Return user info
        CMS->>CMS: Create/update user
        CMS->>User: Redirect to dashboard
    end
    
    alt Multi-Tenant User
        CMS->>CMS: Check user tenants
        alt Single Tenant
            CMS->>CMS: Auto-select tenant
        else Multiple Tenants
            CMS->>User: Show tenant selection
            User->>CMS: Select tenant
        end
        CMS->>CMS: Setup tenant connection
    end
```

### Creating/Updating Content Flow

```mermaid
sequenceDiagram
    participant Admin
    participant CMS
    participant Observer
    participant Moodle API
    participant Moodle DB
    
    Admin->>CMS: Create/Update Course/Section/Activity
    CMS->>CMS: Validate input
    CMS->>CMS: Save to api_moodle table
    
    alt Course Created
        CMS->>Observer: ApiMoodle created (course)
        Observer->>CMS: Create Course record
    end
    
    CMS->>Moodle API: POST core_course_create_courses (if course)
    CMS->>Moodle API: POST local_custom_service_create_activity_* (if activity)
    Moodle API->>Moodle DB: Store content
    Moodle API->>CMS: Return moodle_id
    CMS->>CMS: Update api_moodle.moodle_id
    
    CMS->>Admin: Return success with CMS ID and Moodle ID
```

### Syncing Data to Moodle Flow

```mermaid
sequenceDiagram
    participant CMS
    participant Queue
    participant Job
    participant Moodle API
    participant Moodle DB
    
    CMS->>CMS: User/Enrollment created/updated
    CMS->>Queue: Dispatch sync job
    
    Queue->>Job: ProcessStudentCreationJob
    Job->>Moodle API: POST core_user_create_users
    Moodle API->>Moodle DB: Create user
    Moodle API->>Job: Return moodle_user_id
    Job->>CMS: Update student.moodle_id
    
    Queue->>Job: ProcessStudentEnrollmentRequestJob
    Job->>Moodle API: POST core_enrol_enrol_users
    Moodle API->>Moodle DB: Create enrollment
    Moodle API->>Job: Return success
    Job->>CMS: Update enrollment status
```

### Reading Data from Moodle Flow

```mermaid
sequenceDiagram
    participant CMS
    participant Moodle API
    participant Moodle DB
    participant Sync Job
    
    alt Scheduled Sync (Cron)
        CMS->>Sync Job: ActivityCompletionSyncJob (every 5 min)
        Sync Job->>Moodle API: GET core_completion_get_activities_completion_status
        Moodle API->>Moodle DB: Query completions
        Moodle DB->>Moodle API: Return completion data
        Moodle API->>Sync Job: Return JSON
        Sync Job->>CMS: Update student_activity_progress
    else On-Demand Sync
        CMS->>Moodle API: GET core_course_get_courses
        Moodle API->>Moodle DB: Query courses
        Moodle DB->>Moodle API: Return course data
        Moodle API->>CMS: Return JSON
        CMS->>CMS: Update api_moodle records
    end
```

### Student Enrollment Flow

```mermaid
sequenceDiagram
    participant Admin
    participant CMS
    participant Queue
    participant Job
    participant Moodle API
    
    Admin->>CMS: Enroll student in course
    CMS->>CMS: Create course_student record
    CMS->>Queue: Dispatch ProcessStudentEnrollmentRequestJob
    
    Queue->>Job: Process enrollment
    Job->>CMS: Check if student exists in Moodle
    alt Student not in Moodle
        Job->>Moodle API: POST core_user_create_users
        Moodle API->>Job: Return moodle_user_id
        Job->>CMS: Update student.moodle_id
    end
    
    Job->>Moodle API: POST core_enrol_enrol_users
    Moodle API->>Job: Return enrollment success
    Job->>CMS: Update enrollment status
    Job->>Admin: Notify completion (optional)
```

---

## 7. Moodle Integration (VERY IMPORTANT)

### Why Moodle is Used

Moodle serves as the **Learning Management System (LMS)** that provides:

1. **Proven LMS Functionality**: Mature, feature-rich platform for delivering online courses
2. **Student-Facing Interface**: Professional learning environment for students
3. **Assessment Engine**: Robust quiz and assignment system with grading capabilities
4. **Content Delivery**: Efficient storage and delivery of learning materials
5. **Completion Tracking**: Built-in activity and course completion tracking
6. **Gradebook**: Comprehensive grade management and reporting

### What Data is Stored in Laravel vs Moodle

#### Laravel CMS Stores:
- **Content Metadata**: Course structure, section hierarchy, activity definitions
- **Business Logic**: Enrollment relationships, class assignments, teacher-course mappings
- **User Management**: User accounts, roles, permissions, tenant assignments
- **Aggregated Data**: Student scores (aggregated), exam history summaries
- **Configuration**: Activity settings, quiz templates, rubric templates
- **File Metadata**: S3 file references, upload logs

#### Moodle LMS Stores:
- **Actual Learning Content**: Course content, activity descriptions, question banks
- **Student Submissions**: Quiz answers, assignment submissions, forum posts
- **Detailed Grades**: Per-question scores, attempt details, grade calculations
- **Completion Data**: Source of truth for activity/course completions
- **User Credentials**: Login passwords, session data
- **Media Files**: Referenced in content (actual files may be in S3)

### Sync Strategy

#### 1. **Content Sync (CMS → Moodle)**
- **Method**: REST API calls (synchronous)
- **Trigger**: When content is created/updated in CMS
- **API Endpoints Used**:
  - `core_course_create_courses`: Create courses
  - `local_custom_service_create_activity_quiz`: Create quizzes
  - `local_custom_service_update_activity_quiz`: Update quizzes
  - `local_custom_service_create_activity_assign`: Create assignments
  - `local_custom_service_create_activity_resource`: Create resources
  - `local_custom_service_create_activity_url`: Create URLs
- **Error Handling**: Errors are logged, user is notified
- **Idempotency**: CMS stores `moodle_id` to prevent duplicate creation

#### 2. **User Sync (CMS → Moodle)**
- **Method**: REST API calls (asynchronous via queue)
- **Trigger**: When students/teachers are created in CMS
- **API Endpoint**: `core_user_create_users`
- **Job**: `ProcessStudentCreationJob`
- **Error Handling**: Retry mechanism, fallback to manual creation

#### 3. **Enrollment Sync (CMS → Moodle)**
- **Method**: REST API calls (asynchronous via queue)
- **Trigger**: When students are enrolled in courses
- **API Endpoint**: `core_enrol_enrol_users`
- **Job**: `ProcessStudentEnrollmentRequestJob`
- **Roles**: Teacher (role 3), Student (role 5)

#### 4. **Completion Sync (Moodle → CMS)**
- **Method**: REST API calls (scheduled cron job)
- **Trigger**: Scheduled every 5 minutes
- **API Endpoint**: `core_completion_get_activities_completion_status`
- **Job**: `ActivityCompletionSyncJob`
- **Storage**: Updates `student_activity_progress` table

#### 5. **Course Data Sync (Moodle → CMS)**
- **Method**: REST API calls (on-demand or scheduled)
- **Trigger**: Manual sync or scheduled import
- **API Endpoint**: `core_course_get_courses`, `core_course_get_contents`
- **Use Case**: Initial import, data reconciliation

### Authentication Method with Moodle

**Token-Based Authentication**:
- **Token Location**: `config/services.lms.TOKEN_LMS` (from `.env`)
- **Token Format**: Moodle web service token
- **Usage**: Included in all Moodle API requests
- **Token Generation**: Generated in Moodle admin panel (Site administration → Server → Web services → Manage tokens)

**API Endpoint Configuration**:
- **Base URL**: `config/services.lms.URL_API_LMS` (from `.env`)
- **Format**: `https://moodle.example.com/webservice/rest/server.php?wstoken=TOKEN&wsfunction=FUNCTION_NAME&moodlewsrestformat=json`
- **Method**: POST (for data modification) or GET (for data retrieval)

**Request Example** (from `app/Models/Common.php`):
```php
$url = config('services.lms.URL_API_LMS') . 'core_course_create_courses';
$data = ['courses[0][fullname]' => $courseName, ...];
$response = json_decode(self::execute_curl($url, $data, false, false, 'POST'), true);
```

### Visual Architecture: CMS vs Moodle Responsibilities

```mermaid
graph LR
    subgraph CMS["Laravel CMS<br/>(Management Layer)"]
        A[Content Authoring]
        B[User Management]
        C[Enrollment Management]
        D[Business Logic]
        E[Multi-Tenant Orchestration]
    end
    
    subgraph Moodle["Moodle LMS<br/>(Content Storage & Delivery)"]
        F[Content Storage]
        G[Student Interface]
        H[Assessment Engine]
        I[Gradebook]
        J[Completion Tracking]
    end
    
    A -->|Sync Structure| F
    B -->|Create Users| Moodle
    C -->|Create Enrollments| Moodle
    D -->|Read Completions| J
    E -->|Multi-DB Management| CMS
    
    F -->|Deliver Content| G
    G -->|Submit Answers| H
    H -->|Calculate Grades| I
    I -->|Store Grades| Moodle
    J -->|Sync Status| D
    
    style CMS fill:#e1f5ff
    style Moodle fill:#fff4e1
```

**Key Principle**: 
- **Laravel CMS** = Management & Orchestration
- **Moodle LMS** = Storage & Delivery

---

## 8. Configuration & Environment

### Important .env Variables

#### Application
- `APP_NAME`: Application name
- `APP_ENV`: Environment (local, staging, production)
- `APP_DEBUG`: Debug mode (true/false)
- `APP_URL`: Application base URL

#### Database (Master)
- `DB_CONNECTION`: Database driver (mysql)
- `DB_HOST`: Database host
- `DB_PORT`: Database port (3306)
- `DB_DATABASE`: Master database name
- `DB_USERNAME`: Database username
- `DB_PASSWORD`: Database password

#### Database (Moodle - Optional Direct Access)
- `DB_MOODLE_CONNECTION`: Moodle DB driver
- `DB_MOODLE_HOST`: Moodle DB host
- `DB_MOODLE_DATABASE`: Moodle database name
- `DB_MOODLE_USERNAME`: Moodle DB username
- `DB_MOODLE_PASSWORD`: Moodle DB password
- `DB_MOODLE_PREFIX`: Moodle table prefix (e.g., `spk_`)

#### Moodle Integration
- `URL_LMS`: Moodle base URL
- `TOKEN_LMS`: Moodle web service token
- `URL_API_LMS`: Moodle REST API endpoint (with token)

#### AWS S3
- `AWS_ACCESS_KEY_ID`: AWS access key
- `AWS_SECRET_ACCESS_KEY`: AWS secret key
- `AWS_DEFAULT_REGION`: AWS region
- `AWS_BUCKET`: S3 bucket name
- `AWS_S3_ACCESS_KEY_ID`: S3-specific access key (if different)
- `AWS_S3_SECRET_ACCESS_KEY`: S3-specific secret key
- `AWS_S3_BUCKET`: S3 bucket name
- `AWS_S3_DEFAULT_REGION`: S3 region

#### Queue
- `QUEUE_CONNECTION`: Queue driver (database, redis, sqs)

#### Cache
- `CACHE_DRIVER`: Cache driver (file, redis, database)

#### Authentication
- `KEYCLOAK_CLIENT_ID`: Keycloak client ID
- `KEYCLOAK_CLIENT_SECRET`: Keycloak client secret
- `KEYCLOAK_BASE_URL`: Keycloak base URL
- `KEYCLOAK_REALM`: Keycloak realm name
- `ICANID_DOMAIN`: ICANID domain
- `ICANID_CLIENT_ID`: ICANID client ID
- `ICANID_CLIENT_SECRET`: ICANID client secret
- `GOOGLE_CLIENT_ID`: Google OAuth client ID
- `GOOGLE_CLIENT_SECRET`: Google OAuth client secret

#### Real-time Notifications
- `PUSHER_APP_ID`: Pusher app ID
- `PUSHER_APP_KEY`: Pusher app key
- `PUSHER_APP_SECRET`: Pusher app secret
- `PUSHER_APP_CLUSTER`: Pusher cluster

#### AI Services
- `OPENAI_API_KEY`: OpenAI API key
- `GEMINI_API_KEY`: Google Gemini API key

#### Error Tracking
- `SENTRY_LARAVEL_DSN`: Sentry DSN for error tracking

### Config Files Affecting Behavior

- **`config/services.php`**: External service configurations (Moodle, Keycloak, AWS, Google)
- **`config/database.php`**: Database connections (master, tenant connections, Moodle)
- **`config/filesystems.php`**: Storage disk configurations
- **`config/queue.php`**: Queue driver and connection settings
- **`config/cache.php`**: Cache driver settings
- **`config/auth.php`**: Authentication guards and providers
- **`config/broadcasting.php`**: Real-time broadcasting configuration (Pusher)

### Environments

- **Local**: Development environment
  - Debug mode enabled
  - Local database
  - May use local Moodle instance or staging Moodle

- **Staging**: Pre-production testing
  - Debug mode may be enabled for testing
  - Staging database
  - Staging Moodle instance

- **Production**: Live environment
  - Debug mode disabled
  - Production database
  - Production Moodle instance
  - Error tracking enabled (Sentry)

---

## 9. Security & Permissions

### Authentication Method

**Multi-Provider Authentication**:
1. **Standard Laravel Authentication**: Email/password via `Auth::attempt()`
2. **Keycloak SSO**: OAuth 2.0 flow via `socialiteproviders/keycloak`
3. **ICANID SSO**: Custom OAuth provider via `icanid/icanid-sdk-php`
4. **Google OAuth**: Social login via `laravel/socialite`

**Session Management**:
- Laravel session driver (database/file/redis)
- CSRF protection on all forms
- Remember token for persistent login

### Authorization (Roles, Permissions, Policies)

**Role-Based Access Control (RBAC)**:

1. **Roles**: Defined in `roles` table
   - Common roles: `admin`, `teacher`, `content_editor`, `student`
   - Roles can be tenant-specific

2. **Permissions**: Route-based permissions in `permissions` table
   - Each permission has a `route_name` (e.g., `courses.index`, `students.create`)
   - Permissions are checked via `Helper::checkPermissionUser($routeName)`

3. **Role-Permission Mapping**: Many-to-many via `role_permission` table

4. **User-Role Assignment**: Many-to-many via `user_role` table

**Permission Checking**:
- **Middleware**: `CheckPermission` middleware checks route permissions
- **Helper Function**: `checkPermissionUser($routeName)` validates user has permission
- **Admin Bypass**: Users with `admin` role bypass all permission checks
- **Multi-Tenant**: Permissions are checked against tenant database if user is tenant user

**Policies**: Laravel policies may be used for model-level authorization (if implemented)

### Sensitive Actions and Protections

**Protected Actions**:
- **User Creation/Deletion**: Requires admin role
- **Tenant Management**: Requires `tenant-admin` middleware (hardcoded email check)
- **Course Deletion**: Soft delete with pending deletion queue
- **Bulk Operations**: Rate-limited, logged
- **API Endpoints**: Sanctum token authentication

**Security Measures**:
- **CSRF Protection**: All forms protected
- **SQL Injection Prevention**: Eloquent ORM with parameter binding
- **XSS Protection**: Input sanitization, HTMLPurifier for rich content
- **Password Hashing**: Bcrypt via Laravel's Hash facade
- **API Authentication**: Laravel Sanctum tokens
- **Error Tracking**: Sentry integration for production error monitoring

**Multi-Tenant Isolation**:
- Separate databases per tenant
- Tenant connection validation
- User-tenant assignment verification
- Domain-based tenant routing

---

## 10. Deployment & Runtime

### How the System Runs in Production

**Web Server**:
- PHP-FPM with Nginx/Apache
- Laravel application served via PHP-FPM
- Static assets served directly by web server

**Application Server**:
- Laravel application runs in PHP-FPM workers
- Session storage: Database or Redis
- File storage: Local filesystem + AWS S3

### Queue Workers

**Queue Processing**:
- **Driver**: Database queue (configurable: Redis, SQS, Beanstalkd)
- **Worker Command**: `php artisan queue:work`
- **Supervisor**: Managed via Supervisor for process management
- **Multiple Workers**: Can run multiple workers for different queues

**Important Jobs**:
- `ProcessStudentCreationJob`: Create students in Moodle
- `ProcessStudentEnrollmentRequestJob`: Enroll students in courses
- `ActivityCompletionSyncJob`: Sync activity completions
- `ImportEmsQuestionsJob`: Bulk import questions
- `ProcessNotificationReceiveJob`: Send notifications

**Queue Configuration**:
- Default connection: `database` (from `QUEUE_CONNECTION` env)
- Retry after: 90 seconds (configurable)
- Failed jobs: Stored in `failed_jobs` table

### Cron Jobs / Scheduled Tasks

**Scheduled Tasks** (defined in `routes/console.php`):

1. **Activity Completion Processing**:
   ```php
   Schedule::command('activity:process-pending-completions')
       ->everyFiveMinutes()
   ```
   - Processes pending activity completions

2. **Deletion Queue Processing**:
   ```php
   Schedule::command('deletion:process')
       ->everyMinute()
   ```
   - Processes pending deletions (soft-deleted items)

3. **Log Clearing**:
   ```php
   Schedule::command('log:clear-laravel')
       ->dailyAt('00:00')
   ```
   - Clears Laravel log files daily

4. **Study Session Auto-End**:
   ```php
   Schedule::command('sessions:auto-end')
       ->everyFiveMinutes()
   ```
   - Auto-ends inactive study sessions

5. **Student History Update** (Tenant-specific):
   ```php
   Schedule::command('student-history:update-detail --tenant=ICC')
       ->twiceDaily(12, 0)
   ```
   - Updates student history details for specific tenant

**Cron Setup**:
- Laravel scheduler runs via: `* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1`
- Single cron entry triggers Laravel's scheduler, which manages all scheduled tasks

### Production Considerations

**Performance**:
- **Caching**: Route caching, config caching, view caching
- **Database**: Connection pooling, query optimization
- **Queue**: Multiple workers for parallel processing
- **CDN**: Static assets served via CDN (if configured)

**Monitoring**:
- **Error Tracking**: Sentry for error monitoring
- **Logging**: Laravel logs + application-specific logs
- **Queue Monitoring**: Monitor queue size and failed jobs

**Backup**:
- Database backups (master + tenant databases)
- S3 file backups (if applicable)
- Configuration backups

---

## 11. TL;DR Summary

### System Description (One Sentence)

**Laravel CMS is a multi-tenant content management and orchestration system that manages educational content, users, and enrollments, while Moodle LMS serves as the underlying learning management system that stores and delivers the actual learning content to students.**

### Key Points (5-7 Bullet Points)

1. **Architecture**: Laravel CMS (management layer) + Moodle LMS (content storage & delivery layer) with multi-tenant database architecture

2. **Core Functionality**: Content authoring (courses, sections, activities), user management (students, teachers, admins), enrollment management, and automatic synchronization with Moodle via REST API

3. **Multi-Tenancy**: Supports multiple organizations (tenants) with isolated databases, dynamic connection management, and tenant-specific user assignments

4. **Data Flow**: CMS creates/updates content → Syncs to Moodle via API → Moodle stores and delivers to students → Completion data synced back to CMS

5. **Key Technologies**: Laravel 11, MySQL (multi-database), AWS S3, Queue system (database/Redis), Pusher/Soketi for real-time notifications

6. **Authentication**: Multi-provider support (Laravel auth, Keycloak SSO, ICANID SSO, Google OAuth) with role-based access control (RBAC)

7. **Asynchronous Processing**: Heavy operations (user creation, enrollments, imports) processed via queue jobs for better performance and reliability

---

## Appendix: Key File Locations

### Important Files for Developers

- **Moodle API Wrapper**: `app/Models/Common.php`
- **Moodle Service Layer**: `app/ApiService/FeService.php`
- **Permission Checking**: `app/Helpers/Helper.php` (function `checkPermissionUser`)
- **Tenant Management**: `app/Helpers/HelperTenant.php`
- **Content Management**: `app/Http/Controllers/ProductController.php`
- **Course Management**: `app/Http/Controllers/CourseController.php`
- **Moodle Integration**: `app/Http/Controllers/ApiMoodleController.php`
- **Scheduled Tasks**: `routes/console.php`
- **Moodle Configuration**: `config/services.php` (lms section)

### Database Schema Files

- **Migrations**: `database/migrations/`
- **Seeders**: `database/seeders/`

### Configuration Files

- **Services**: `config/services.php`
- **Database**: `config/database.php`
- **Queue**: `config/queue.php`
- **Filesystems**: `config/filesystems.php`

---

**Document Version**: 1.0  
**Last Updated**: 2025-01-XX  
**Maintained By**: Development Team