# CEPI LMS — Architecture

> **Source of truth.** Last updated: 2026-06-02. Verified directly from codebase.

---

## 1. Project Overview

CEPI LMS is a Laravel-based e-learning platform targeting Pakistani FSc and entry-test students. It delivers structured, video-first courses over the web, with plans for a Flutter mobile app on Android and iOS.

Key characteristics:
- Strict **Course → Module → Lesson** content hierarchy
- Protected video delivery via **Bunny.net** signed URLs
- **Device binding** security: one browser per account with admin override
- Dual payment flow: **manual bank transfer** (live) + JazzCash/Stripe stubs (skeleton only)
- Role-based access: **Admin**, **Instructor**, **Student**

---

## 2. Confirmed Technology Stack

| Layer | Technology | Version | Status |
|---|---|---|---|
| Language | PHP | ^8.3 | ✅ Confirmed |
| Framework | Laravel | ^13.0 | ✅ Confirmed |
| Frontend templates | Blade | (Laravel built-in) | ✅ Confirmed |
| CSS framework | Tailwind CSS | ^3.1 | ✅ Confirmed |
| JS reactivity | Alpine.js | ^3.4.2 | ✅ Confirmed |
| Build tool | Vite | ^8.0 | ✅ Confirmed |
| HTTP client (frontend) | Axios | ^1.11 | ✅ Confirmed |
| Auth scaffolding | Laravel Breeze | ^2.4 | ✅ Confirmed |
| Role/Permission | spatie/laravel-permission | ^7.2 | ✅ Confirmed |
| Social auth | Laravel Socialite | ^5.26 | ✅ Confirmed (Google) |
| Database (dev) | SQLite | (file-based) | ✅ `.env.example` |
| Database (prod) | MySQL | (assumed) | ⚠️ Not confirmed in .env.production |
| Queue / Cache / Sessions | Database driver | (Laravel default) | ✅ Confirmed |
| Video CDN | Bunny Stream | — | ✅ Integrated |
| Video DRM / Signing | Bunny Token Auth (HMAC-SHA256) | — | ✅ Implemented |
| Payment (live) | Bank Transfer (manual) | — | ✅ Fully implemented |
| Payment (stub) | JazzCash | — | ⚠️ Skeleton only |
| Payment (stub) | Stripe | — | ⚠️ Skeleton only |
| Mobile API | None yet | — | ❌ Not implemented |
| API auth (mobile) | None yet | — | ❌ Laravel Sanctum not installed |

---

## 3. High-Level System Architecture

```mermaid
graph TD
    Browser["Web Browser"]
    MobileApp["Flutter Mobile App (planned)"]
    Laravel["Laravel 13 Application"]
    DB["Database (SQLite dev / MySQL prod)"]
    Bunny["Bunny.net Stream CDN"]
    Gateway["Payment Gateways (Bank Transfer / JazzCash / Stripe)"]
    Mail["Mail (log driver in dev)"]
    Google["Google OAuth"]

    Browser -->|HTTPS / Blade| Laravel
    MobileApp -->|REST API - not yet built| Laravel
    Laravel -->|Queries| DB
    Laravel -->|Signed embed URL| Bunny
    Browser -->|Video playback| Bunny
    MobileApp -->|Video playback planned| Bunny
    Laravel -->|Payment initiation| Gateway
    Gateway -->|Webhook callback| Laravel
    Laravel -->|Email| Mail
    Browser -->|OAuth| Google
    Google -->|Callback| Laravel
```

---

## 4. User Roles

| Role | Storage | Access Area |
|---|---|---|
| **Student** | `user_type = student` + Spatie role | Course catalog, enrollment, lesson player, dashboard |
| **Instructor** | `user_type = instructor` + Spatie role | Own course CRUD, module/lesson management, enrollment view |
| **Admin** | `user_type = admin` + Spatie role | Full platform — users, courses, payments, settings, media, blog |
| **Guest** | Unauthenticated | Public catalog, blog, about, contact, course detail (no player) |

---

## 5. LMS Module Overview

| Module | Status |
|---|---|
| User registration / login / Google OAuth | ✅ Implemented |
| Email verification (6-digit code) | ✅ Implemented |
| Device binding (browser lock, cooldown) | ✅ Implemented |
| Course catalog (public) | ✅ Implemented |
| Course detail page (public) | ✅ Implemented |
| Course CRUD (admin + instructor) | ✅ Implemented |
| Module/Lesson CRUD (admin) | ✅ Implemented (AJAX apiResource) |
| Enrollment (admin manual, auto free, bank transfer) | ✅ Implemented |
| Student lesson player (Bunny embed) | ✅ Implemented |
| Lesson progress tracking (watch seconds, position, completion) | ✅ Implemented |
| Course progress percent | ✅ Implemented |
| Student dashboard | ✅ Implemented |
| Instructor dashboard | ✅ Implemented |
| Admin dashboard | ✅ Implemented |
| Manual bank transfer checkout | ✅ Implemented |
| Admin payment review / approval | ✅ Implemented |
| Blog (public, admin CRUD) | ✅ Implemented |
| Media library (admin) | ✅ Implemented |
| Categories (admin) | ✅ Implemented |
| Settings (key-value store) | ✅ Implemented |
| Admin audit log | ✅ Schema exists, partial usage |
| Course reviews / ratings | ✅ Schema + model, UI unclear |
| Quizzes | ✅ Schema + model, UI unclear |
| JazzCash payment | ⚠️ Skeleton only (not functional) |
| Stripe payment | ⚠️ Skeleton only (not functional) |
| Certificates | ❌ Not implemented |
| Notifications (email/SMS/WhatsApp) | ❌ Not implemented beyond email verification |
| REST API for mobile | ❌ Not implemented |
| Laravel Sanctum (API auth) | ❌ Not installed |
| Push notifications | ❌ Not implemented |
| Offline / download content | ❌ Not implemented |

---

## 6. Web Application Directory Map

```
routes/
  web.php          — All web routes (public, auth-protected, admin, instructor, student)
  auth.php         — Auth routes (login, register, password reset, Google OAuth, device policy)

app/Http/Controllers/
  Auth/            — Breeze auth + SocialAuthController + DeviceBinding acknowledge
  Admin/           — Full admin CRUD (users, courses, modules, lessons, enrollments, payments, settings, media, blog, categories, video)
  Instructor/      — Instructor dashboard + course management
  Student/         — LessonController (course hub, lesson show, progress toggle)
  CheckoutController.php              — Stripe/JazzCash initiation (stub)
  ManualCourseCheckoutController.php  — Bank transfer checkout (live)
  DashboardController.php             — Unified dashboard dispatcher (admin/instructor/student)
  PublicCourseController.php          — Public catalog + course detail
  PublicBlogController.php            — Public blog listing + post
  PublicPageController.php            — About, Contact
  HomeController.php                  — Landing page
  SitemapController.php               — sitemap.xml

app/Services/
  BunnyVideoService.php       — Signed URL generation, video creation via Bunny API
  DeviceBindingService.php    — Device fingerprint, cookie token, cooldown logic
  AdminMediaService.php       — Media library management
  SitemapService.php          — Sitemap cache management
  Payments/
    JazzCashGateway.php       — Skeleton
    StripeGateway.php         — Skeleton

app/Models/
  User, Course, CourseModule, Lesson, Enrollment, LessonProgress,
  Payment, UserDevice, Category, BlogPost, MediaLibrary, Setting,
  AdminLog, ContactMessage, CourseReview, Quiz

resources/views/
  layouts/         — app, admin, guest, public layouts
  components/      — Breeze defaults + ui/ subfolder
  dashboard/       — student, instructor, admin dashboards
  student/lessons/ — hub (syllabus), show (player)
  admin/           — Full admin CRUD views
  courses/         — Public listing + detail
  payments/        — Manual checkout
  auth/            — Login, register, verification, password
```

---

## 7. API Architecture (Current State)

There is **no dedicated API layer**. No `routes/api.php` exists. The app is a traditional Blade-rendered MVC with three JSON-returning endpoints:
- Module/Lesson CRUD (admin `apiResource`)
- Lesson progress toggle (`Student\LessonController@toggleProgress`)
- Video upload initiation (`Admin\VideoController@store`)

**Laravel Sanctum is not installed.** All mobile API work requires: installing Sanctum, creating `routes/api.php`, building versioned API controllers and JSON resources.

---

## 8. Third-Party Integrations

| Integration | Purpose | Status |
|---|---|---|
| **Bunny Stream** | Video hosting, signed token playback | ✅ Live |
| **Bunny Token Auth** | HMAC-SHA256 signed embed URLs | ✅ Live |
| **Google OAuth** | Social login via Socialite | ✅ Live |
| **JazzCash** | PKR payment gateway | ⚠️ Skeleton |
| **Stripe** | International card payments | ⚠️ Skeleton |
| **Mail** | Email verification (log driver in dev) | ✅ Framework ready |
| **SMS/WhatsApp** | Notifications | ❌ Not integrated |

---

## 9. Recommended Next Phases

**Phase A — API Foundation (required before Flutter)**
1. Install Laravel Sanctum
2. Create `routes/api.php` with versioned routes (`/api/v1/`)
3. Build API resource controllers and JSON transformers
4. Mobile auth endpoints (login, register, token refresh, logout)

**Phase B — Flutter Mobile App MVP**
1. Flutter project scaffold with Riverpod + Go Router
2. Auth screens (login, register, Google Sign-In)
3. Course catalog and detail
4. Enrollment and payment flows
5. Lesson player with Bunny embed
6. Progress sync

**Phase C — Payment Hardening**
1. Complete JazzCash integration (live credentials, secure hash verification)
2. Complete Stripe integration (`stripe/stripe-php`, webhook verification)

**Phase D — Advanced Features**
1. Certificates
2. SMS/WhatsApp notifications
3. Quiz UI and grading
4. Course reviews UI
5. Analytics dashboard