Skip to content

thetealteam/the-LMS-status

BranchesTags

Repository files navigation

School Management System API (v3)

A comprehensive Laravel-based School Management System with robust Role-Based Access Control (RBAC), multilingual support (English/Khmer), and auto-grading capabilities.

🏗️ System Architecture

graph TB
    subgraph "Client Layer"
        A[Postman/API Client]
    end
    
    subgraph "API Layer"
        B[Laravel Routes<br/>api/v3/*]
        C[Sanctum Auth<br/>Middleware]
    end
    
    subgraph "Business Logic"
        D[Controllers]
        E[Policies<br/>RBAC]
        F[Services]
    end
    
    subgraph "Data Layer"
        G[Eloquent Models]
        H[MySQL Database]
    end
    
    A -->|HTTP + JSON| B
    B --> C
    C --> D
    D --> E
    D --> F
    F --> G
    G --> H
Loading

📊 Entity Relationship Diagram

erDiagram
    USERS ||--o{ STUDENTS : "has profile"
    USERS ||--o{ ROOMS : "manages (teacher)"
    USERS }o--o{ STUDENTS : "parent-child"
    
    ROOMS ||--o{ STUDENTS : "enrolled in"
    ROOMS }o--|| USERS : "taught by"
    
    STUDENTS ||--o{ ENROLLMENTS : "has"
    STUDENTS ||--o{ PAYMENTS : "makes"
    STUDENTS ||--o{ PERFORMANCE_RECORDS : "has"
    STUDENTS ||--o{ ACADEMIC_RECORDS : "has"
    
    ROOMS ||--o{ ENROLLMENTS : "contains"
    
    USERS {
        int id PK
        string name
        string email UK
        string password
        enum role
        timestamps
    }
    
    STUDENTS {
        int id PK
        string student_code UK
        string english_name
        string khmer_name
        enum gender
        date date_of_birth
        decimal price
        int user_id FK
        int room_id FK
        timestamps
    }
    
    ROOMS {
        int id PK
        string room_number UK
        string khmer_name
        enum gender
        decimal price
        enum status
        int teacher_id FK
        timestamps
    }
    
    PERFORMANCE_RECORDS {
        int id PK
        int student_id FK
        string subject
        decimal score
        string grade
        string evaluation_type
        timestamps
    }
    
    PAYMENTS {
        int id PK
        int student_id FK
        date payment_date
        decimal price
        decimal total_amount
        enum payment_status
        timestamps
    }
Loading

👥 User Roles & Permissions

graph LR
    subgraph "Admin (Full Access)"
        A1[User CRUD]
        A2[System CRUD]
        A3[All Activities]
    end
    
    subgraph "Staff (Operational)"
        S1[Create Teacher/Student/Parent]
        S2[Manage Rooms]
        S3[Student Activities]
        S4[❌ Cannot Create Admin]
    end
    
    subgraph "Teacher (Restricted)"
        T1[View Assigned Rooms]
        T2[Manage Student Scores]
        T3[❌ Cannot Create Users]
    end
    
    subgraph "Student (Read-Only)"
        ST1[View Own Profile]
        ST2[View Own Scores]
        ST3[❌ Cannot Modify]
    end
    
    subgraph "Parent (Read-Only)"
        P1[View Children Profiles]
        P2[View Children Scores]
        P3[❌ Cannot Modify]
    end
Loading

🔐 Authentication Flow

sequenceDiagram
    participant C as Client
    participant API as API Server
    participant Auth as AuthController
    participant DB as Database
    participant Sanctum as Laravel Sanctum
    
    C->>API: POST /api/v3/register
    API->>Auth: Validate & Hash Password
    Auth->>DB: Create User
    DB-->>Auth: User Created
    Auth-->>C: 201 Created
    
    C->>API: POST /api/v3/login
    API->>Auth: Validate Credentials
    Auth->>DB: Find User by Email
    DB-->>Auth: User Data
    Auth->>Auth: Hash::check(password)
    Auth->>Sanctum: createToken(abilities)
    Sanctum-->>Auth: Bearer Token
    Auth-->>C: 200 OK + Token
    
    C->>API: GET /api/v3/users<br/>(Authorization: Bearer {token})
    API->>Sanctum: Validate Token
    Sanctum->>DB: Retrieve User
    DB-->>Sanctum: User Data
    Sanctum-->>API: Authenticated User
    API-->>C: 200 OK + Data
Loading

🎯 Complete User Workflows

Admin Workflow

flowchart TD
    A[Admin Login] --> B{Action?}
    B -->|User Management| C[CRUD Users<br/>All Roles]
    B -->|System Management| D[CRUD Rooms/Students]
    B -->|Activity Management| E[CRUD All Records]
    
    C --> F[Create Staff]
    C --> G[Create Teacher]
    C --> H[Create Student]
    C --> I[Create Parent]
    
    D --> J[Manage Rooms]
    D --> K[Manage Students]
    
    E --> L[Performance Records]
    E --> M[Academic Records]
    E --> N[Payments]
    E --> O[Enrollments]
Loading

Staff Workflow

flowchart TD
    A[Staff Login] --> B{Action?}
    B -->|User Creation| C[Create Teacher/Student/Parent]
    B -->|Room Management| D[Create/Update Rooms]
    B -->|Student Activities| E[Manage All Student Data]
    
    C --> F[✅ Create Teacher]
    C --> G[✅ Create Student]
    C --> H[✅ Create Parent]
    C --> I[❌ Create Admin<br/>403 Forbidden]
    
    E --> J[Add Performance Records]
    E --> K[Add Payments]
    E --> L[Manage Enrollments]
    
    J --> M[Auto-Grade Calculation<br/>Score → Grade A-F]
Loading

Teacher Workflow

flowchart TD
    A[Teacher Login] --> B{Action?}
    B -->|View| C[My Assigned Rooms]
    B -->|Manage| D[Student Scores]
    
    C --> E[List Rooms<br/>teacher_id = me]
    
    D --> F[Add Performance Record]
    D --> G[Update Performance Record]
    
    F --> H[Auto-Grade<br/>95 → A]
    
    B -->|Forbidden| I[❌ Create Users<br/>403]
    B -->|Forbidden| J[❌ Delete Records<br/>403]
Loading

Student/Parent Workflow

flowchart TD
    A[Student/Parent Login] --> B{Action?}
    B -->|View| C[Own Profile/Children]
    B -->|View| D[Performance Records]
    B -->|View| E[Academic Records]
    B -->|View| F[Payment History]
    
    B -->|Forbidden| G[❌ Create/Update/Delete<br/>403]
Loading

🔄 API Endpoint Flows

User Management Flow

sequenceDiagram
    participant Admin
    participant API
    participant UserController
    participant UserPolicy
    participant DB
    
    Admin->>API: POST /api/v3/users<br/>{role: "staff"}
    API->>UserController: store(request)
    UserController->>UserPolicy: authorize('create')
    UserPolicy-->>UserController: ✅ Allowed
    UserController->>UserController: Validate Data
    UserController->>UserController: Hash Password
    UserController->>DB: Create User
    DB-->>UserController: User Created
    UserController-->>Admin: 201 Created
    
    Note over Admin,DB: Staff tries to create Admin
    
    Admin->>API: POST /api/v3/users<br/>{role: "admin"}
    API->>UserController: store(request)
    UserController->>UserController: Check hasRole('staff')
    UserController-->>Admin: 403 Forbidden<br/>"Unauthorized to create Admin"
Loading

Performance Record Flow (Auto-Grading)

sequenceDiagram
    participant Staff
    participant API
    participant PerfController
    participant PerfPolicy
    participant DB
    
    Staff->>API: POST /api/v3/performance-records<br/>{score: 95}
    API->>PerfController: store(request)
    PerfController->>PerfPolicy: authorize('create')
    PerfPolicy-->>PerfController: ✅ Allowed
    PerfController->>PerfController: Validate Data
    PerfController->>PerfController: calculateGrade(95)
    Note over PerfController: 90-100 → A<br/>80-89 → B<br/>70-79 → C<br/>60-69 → D<br/>50-59 → E<br/>0-49 → F
    PerfController->>DB: Create Record<br/>{score: 95, grade: "A"}
    DB-->>PerfController: Record Created
    PerfController-->>Staff: 201 Created<br/>{grade: "A"}
Loading

Room Management Flow

sequenceDiagram
    participant Staff
    participant API
    participant RoomController
    participant RoomPolicy
    participant DB
    
    Staff->>API: POST /api/v3/rooms<br/>{teacher_id: 3}
    API->>RoomController: store(request)
    RoomController->>RoomPolicy: authorize('create')
    RoomPolicy-->>RoomController: ✅ Staff Allowed
    RoomController->>DB: Create Room
    DB-->>RoomController: Room Created
    RoomController-->>Staff: 201 Created
    
    Note over Staff,DB: Teacher views their rooms
    
    Staff->>API: GET /api/v3/rooms
    API->>RoomController: index(request)
    RoomController->>RoomController: Check User Role
    Note over RoomController: Teacher → Filter by teacher_id<br/>Staff/Admin → All Rooms
    RoomController->>DB: Query Rooms
    DB-->>RoomController: Filtered Results
    RoomController-->>Staff: 200 OK + Rooms
Loading

📋 Complete Activity Matrix

Activity Admin Staff Teacher Student Parent
User Management
Create Admin ✅ ❌ ❌ ❌ ❌
Create Staff ✅ ❌ ❌ ❌ ❌
Create Teacher ✅ ✅ ❌ ❌ ❌
Create Student ✅ ✅ ❌ ❌ ❌
Create Parent ✅ ✅ ❌ ❌ ❌
Update Users ✅ ✅* ❌ ❌ ❌
Delete Users ✅ ❌ ❌ ❌ ❌
Room Management
Create Room ✅ ✅ ❌ ❌ ❌
View Rooms ✅ ✅ ✅** ❌ ❌
Update Room ✅ ✅ ❌ ❌ ❌
Delete Room ✅ ✅ ❌ ❌ ❌
Student Management
Create Student Profile ✅ ✅ ❌ ❌ ❌
View Students ✅ ✅ ✅** ✅*** ✅***
Update Student ✅ ✅ ❌ ❌ ❌
Delete Student ✅ ✅ ❌ ❌ ❌
Performance Records
Create Record ✅ ✅ ✅** ❌ ❌
View Records ✅ ✅ ✅** ✅*** ✅***
Update Record ✅ ✅ ✅** ❌ ❌
Delete Record ✅ ✅ ❌ ❌ ❌
Academic Records
Create Record ✅ ✅ ✅** ❌ ❌
View Records ✅ ✅ ✅** ✅*** ✅***
Update Record ✅ ✅ ✅** ❌ ❌
Delete Record ✅ ✅ ❌ ❌ ❌
Payments
Create Payment ✅ ✅ ❌ ❌ ❌
View Payments ✅ ✅ ❌ ✅*** ✅***
Update Payment ✅ ✅ ❌ ❌ ❌
Delete Payment ✅ ✅ ❌ ❌ ❌
Enrollments
Create Enrollment ✅ ✅ ❌ ❌ ❌
View Enrollments ✅ ✅ ✅** ✅*** ✅***
Update Enrollment ✅ ✅ ❌ ❌ ❌
Delete Enrollment ✅ ✅ ❌ ❌ ❌

Legend:

  • * Staff cannot update/delete Admin users
  • ** Teachers can only access records for their assigned rooms/students
  • *** Students/Parents can only view their own/linked children's records

🚀 Quick Start

Prerequisites

  • PHP 8.1+
  • Composer
  • MySQL 8.0+
  • Laravel 11.x

Installation

# Clone repository
git clone <repository-url>
cd the-LMS

# Install dependencies
composer install

# Configure environment
cp .env.example .env
php artisan key:generate

# Configure database in .env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=school_management
DB_USERNAME=root
DB_PASSWORD=

# Run migrations
php artisan migrate:fresh --seed

# Start server
php artisan serve

API Base URL

http://127.0.0.1:8000/api/v3

📡 API Endpoints

Authentication

POST   /register          - Register new user
POST   /login             - Login and get token
POST   /logout            - Logout (revoke token)

Users

GET    /users             - List all users
POST   /users             - Create user
GET    /users/{id}        - Show user
PUT    /users/{id}        - Update user
DELETE /users/{id}        - Delete user

Rooms

GET    /rooms             - List rooms
POST   /rooms             - Create room
GET    /rooms/{id}        - Show room
PUT    /rooms/{id}        - Update room
DELETE /rooms/{id}        - Delete room

Students

GET    /students          - List students
POST   /students          - Create student
GET    /students/{id}     - Show student
PUT    /students/{id}     - Update student
DELETE /students/{id}     - Delete student

Performance Records

GET    /performance-records          - List records
POST   /performance-records          - Create record (auto-grade)
GET    /performance-records/{id}     - Show record
PUT    /performance-records/{id}     - Update record
DELETE /performance-records/{id}     - Delete record

Academic Records

GET    /academic-records          - List records
POST   /academic-records          - Create record
GET    /academic-records/{id}     - Show record
PUT    /academic-records/{id}     - Update record
DELETE /academic-records/{id}     - Delete record

Payments

GET    /payments          - List payments
POST   /payments          - Create payment
GET    /payments/{id}     - Show payment
PUT    /payments/{id}     - Update payment
DELETE /payments/{id}     - Delete payment

Enrollments

GET    /enrollments          - List enrollments
POST   /enrollments          - Create enrollment
GET    /enrollments/{id}     - Show enrollment
PUT    /enrollments/{id}     - Update enrollment
DELETE /enrollments/{id}     - Delete enrollment

🧪 Testing with Postman

Import Collection

  1. Import school_management_system_v3_full.postman_collection.json
  2. Set environment variable base_url to http://127.0.0.1:8000/api/v3

Run Complete Flow

  1. 00. Bootstrap - Register Admin
  2. 01. Admin Workflows - Full system access
  3. 02. Staff Workflows - Operational tasks
  4. 03. Teacher Workflows - Restricted access
  5. 04. Student Workflows - Read-only access

Key Features

  • ✅ Automated token capture
  • ✅ Chained requests with environment variables
  • ✅ Negative test cases (403 Forbidden)
  • ✅ Auto-grade verification

🎓 Auto-Grading System

graph LR
    A[Score Input] --> B{Score Range}
    B -->|90-100| C[Grade: A]
    B -->|80-89| D[Grade: B]
    B -->|70-79| E[Grade: C]
    B -->|60-69| F[Grade: D]
    B -->|50-59| G[Grade: E]
    B -->|0-49| H[Grade: F]
Loading

Implementation:

private function calculateGrade($score): string
{
    return match(true) {
        $score >= 90 => 'A',
        $score >= 80 => 'B',
        $score >= 70 => 'C',
        $score >= 60 => 'D',
        $score >= 50 => 'E',
        default => 'F'
    };
}

🔒 Security Features

RBAC Implementation

  • Policy-Based Authorization: Each model has a dedicated Policy
  • Middleware Protection: All routes protected by auth:sanctum
  • Token Scoping: Role-based abilities assigned to tokens
  • Password Hashing: Bcrypt with automatic hashing

Security Checks

flowchart TD
    A[API Request] --> B{Valid Token?}
    B -->|No| C[401 Unauthorized]
    B -->|Yes| D{Policy Check}
    D -->|Denied| E[403 Forbidden]
    D -->|Allowed| F{Validation}
    F -->|Failed| G[422 Unprocessable]
    F -->|Passed| H[Process Request]
    H --> I[200/201 Success]
Loading

🌐 Multilingual Support

All text fields support both English and Khmer:

  • english_name / khmer_name
  • english_description / khmer_description
  • File uploads with language-specific metadata

📝 License

This project is proprietary software. All rights reserved.

👨‍💻 Development Team

Developed with ❤️ for modern educational institutions.

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages