System Architecture

​

Overview

​

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
│  Next.js App Router • React 19 • TanStack Query • Tailwind  │
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│                    Application Layer                         │
│  Server Components • API Routes • Server Actions • Middleware│
└──────────────────┬──────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│                     Service Layer                            │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Supabase │  │   AWS    │  │ Payment  │  │  Email   │   │
│  │   Auth   │  │ S3/CDN   │  │ Gateways │  │ SendGrid │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────────────┐
│                      Data Layer                              │
│            Supabase PostgreSQL with RLS                      │
└─────────────────────────────────────────────────────────────┘

​

Tech Stack

​

Frontend

• Framework: Next.js 16 with App Router
• Language: TypeScript 5.0+
• UI Library: React 19
• Styling: Tailwind CSS
• Components: Radix UI + shadcn/ui
• State Management: TanStack Query (React Query)
• Forms: React Hook Form + Zod validation
• Video Player: Media Chrome for HLS streaming

​

Backend

• Runtime: Node.js 18.0+
• Database: Supabase (PostgreSQL)
• Authentication: Supabase Auth with Row Level Security (RLS)
• File Storage: AWS S3 + CloudFront/Azure Front Door CDN
• Video Processing: AWS MediaConvert for HLS transcoding
• Payments: Stripe & Flutterwave
• Email: SendGrid
• PDF Generation: PDFKit with custom fonts

​

Infrastructure

• Monorepo: Turborepo
• Package Manager: npm 10.0+
• Deployment: Vercel (recommended) or self-hosted
• CDN: CloudFront or Azure Front Door

​

Monorepo Structure

easelms/
├── apps/
│   ├── lms/                    # Main LMS application
│   │   ├── app/                # Next.js App Router
│   │   │   ├── admin/          # Admin dashboard
│   │   │   ├── learner/        # Learner interface
│   │   │   ├── api/            # API routes
│   │   │   └── auth/           # Authentication pages
│   │   ├── components/         # React components
│   │   ├── lib/                # Utilities and services
│   │   └── supabase/           # Database migrations
│   └── website/                # Marketing landing page
├── package.json                # Root workspace config
└── turbo.json                  # Turborepo configuration

### Workspace Configuration

The monorepo uses npm workspaces with Turborepo for build optimization:

```json title="package.json"
{
  "name": "easelms-monorepo",
  "private": true,
  "workspaces": ["apps/*"],
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "lint": "turbo run lint"
  }
}

​

Turborepo Pipeline

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

​

Application Architecture

​

Middleware Layer

import { updateSession } from "@/lib/supabase/middleware"
import { NextResponse } from "next/server"
import type { NextRequest } from "next/server"

export async function middleware(request: NextRequest) {
  // Handle CORS for API routes
  if (request.nextUrl.pathname.startsWith('/api/')) {
    const allowedOrigin = process.env.NEXT_PUBLIC_WEBSITE_URL || '*'
    
    if (request.method === 'OPTIONS') {
      return new NextResponse(null, {
        status: 200,
        headers: {
          'Access-Control-Allow-Origin': allowedOrigin,
          'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
        },
      })
    }
  }
  
  // Update Supabase session
  return await updateSession(request)
}

​

Route Protection

• Public routes: /auth/*, /forgot-password
• Admin routes: /admin/* (requires user_type = 'admin')
• Learner routes: /learner/* (requires authenticated user)

​

Data Flow

1. Client Request → Server Component/API Route
2. Authentication → Supabase Auth validates session
3. Authorization → Row Level Security (RLS) enforces permissions
4. Data Fetching → TanStack Query with cache management
5. Response → Server-rendered or JSON response

​

Database Schema

​

Core Tables

• profiles - User profiles with role-based access
• courses - Course metadata and settings
• lessons - Course content with video/resources
• enrollments - Student course enrollments
• progress - Lesson completion tracking
• payments - Payment records
• certificates - Generated certificates
• quiz_questions, quiz_attempts, quiz_results - Assessment system
• platform_settings - Branding and configuration

​

Row Level Security

• Admins can access all data
• Instructors can access their courses
• Learners can only access enrolled courses
• Public can view published course listings

​

Caching Strategy

export const CACHE_TIMES = {
  COURSES: 5 * 60 * 1000,      // 5 minutes
  LESSONS: 10 * 60 * 1000,     // 10 minutes
  PROFILE: 30 * 60 * 1000,     // 30 minutes
  SETTINGS: 60 * 60 * 1000,    // 1 hour
}

​

Cache Invalidation

• Mutations automatically invalidate related queries
• Realtime subscriptions update cache on data changes
• Manual invalidation for critical updates

​

Deployment Architecture

​

Recommended Setup

┌──────────────┐
│   Vercel     │ ← Next.js App (SSR + API Routes)
└──────┬───────┘
       │
       ├─────→ Supabase (Database + Auth)
       ├─────→ AWS S3 (File Storage)
       ├─────→ CloudFront/Azure FD (CDN)
       ├─────→ AWS MediaConvert (Video Processing)
       ├─────→ Stripe/Flutterwave (Payments)
       └─────→ SendGrid (Emails)

​

Scaling Considerations

• Horizontal scaling: Next.js serverless functions auto-scale
• Database: Supabase connection pooling
• CDN: Global edge caching for video/assets
• Video processing: Async job queue with MediaConvert

​

Performance Optimizations

1. Server Components: Reduce client-side JavaScript
2. HLS Streaming: Adaptive bitrate video delivery
3. Image Optimization: Next.js automatic image optimization
4. Code Splitting: Dynamic imports for heavy components
5. Database Indexes: Optimized queries on frequently accessed tables
6. CDN Caching: Static assets served from edge locations

​

Security Features

• Authentication: Supabase Auth with email/password
• Authorization: Row Level Security (RLS) policies
• CORS: Configured middleware for cross-origin requests
• Environment Variables: Secrets managed securely
• Input Validation: Zod schemas for all forms
• SQL Injection Protection: Parameterized queries via Supabase client

​

Development Workflow

# Install dependencies
npm install

# Start development servers (both apps)
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

​

Environment Setup

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_key
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key

​

Next Steps