Technical Architecture: Serverless REST API Stack

Overview

A modern serverless architecture using REST API with AWS API Gateway, optimized for simplicity, reliability, and cost-effectiveness. The system uses Lambda functions for business logic, Aurora Serverless for database, and Step Functions for AI content generation workflows. Designed for rapid development and easy debugging while maintaining scalability.

Architecture Components

Frontend Layer

  • AWS Amplify Hosting
    • Next.js 14 with TypeScript and App Router
    • Server-side rendering (SSR) and static generation
    • CloudFront CDN for global content delivery
    • Built-in CI/CD from Git (automatic deployments)
    • Environment variable management
  • Frontend Libraries
    • amazon-cognito-identity-js for authentication
    • Custom API client with TypeScript types
    • TailwindCSS for styling
    • React Quill for rich text editing
    • Recharts for analytics visualization

API Layer

  • AWS API Gateway (REST)
    • RESTful API endpoints (/courses, /lessons, /enrollments, /progress, /users, /analytics, /ai-generation, /badges, /recommendations)
    • API key requirement for all requests
    • Cognito User Pool authorizer for authentication
    • Request/response validation
    • Usage plans and throttling for rate limiting
    • CloudWatch logging for all requests
    • CORS configuration for frontend access
  • AWS Lambda Functions
    • TypeScript handlers for all API endpoints
    • Organized by service domain (courses, lessons, enrollments, etc.)
    • Shared utilities layer for common functions
    • Business logic implementation
    • Database operations via Aurora Data API
    • Integration with third-party services (Bedrock, HeyGen, Stripe)
    • Environment-based configuration

Authentication & Authorization

  • AWS Cognito User Pools
    • User authentication and management
    • User groups (admin, premium, free)
    • Social login (Google, Facebook, Apple)
    • JWT token-based authentication
    • Custom attributes for user profiles
    • MFA support
  • API Gateway Authorization
    • Cognito User Pool authorizer
    • JWT token validation on all protected endpoints
    • Role-based access control via Cognito groups
    • API key validation for additional security layer

Database Layer

  • Amazon Aurora Serverless v2 (PostgreSQL)
    • Auto-scaling based on load (0.5 ACU to 128 ACU)
    • Pay-per-second billing
    • Automatic pause for no activity (optional)
    • Data API for HTTP-based queries (from Lambda, no VPC needed)
    • Schema:
      • Relational design with proper normalization
      • JSON columns for flexible lesson metadata
      • Full-text search capabilities
    • Automated backups and snapshots
  • Amazon DynamoDB (Optional)
    • User progress tracking (high write throughput)
    • Real-time analytics
    • DynamoDB Streams → Lambda for aggregations

Caching Layer

  • Amazon ElastiCache Serverless (Redis)
    • Provisioned but deferred for MVP (traffic < 10K requests/hour)
    • Future use cases: session state, course catalog caching, leaderboards
    • Can be enabled when database performance optimization is needed
  • API Gateway Caching
    • Available for frequently accessed read-only endpoints
    • Configurable TTL per endpoint

Content Storage & Delivery

  • Amazon S3
    • Video files (multi-part upload support)
    • AI-generated documents
    • User avatars and uploads
    • Presigned URLs for secure uploads
  • Amazon CloudFront
    • Global CDN
    • Signed URLs/Cookies for premium content
    • Lambda@Edge for URL rewriting and auth checks
  • AWS MediaConvert
    • Video transcoding to multiple formats
    • Adaptive bitrate streaming (HLS/DASH)
    • Thumbnail generation

AI Content Generation Pipeline

  • AWS Step Functions (Express Workflows)
    • Orchestrate multi-step AI generation
    • Parallel processing (text + video generation)
    • Error handling and retries
    • Cost-effective for short-duration workflows
  • Amazon Bedrock
    • Claude for course content writing
    • Lesson plans, action items, reading material
    • Knowledge bases for context-aware generation
  • Amazon SageMaker (Optional)
    • Custom AI models if needed
    • Fine-tuned models for specific domains
  • Third-party Video AI Services
    • Synthesia, D-ID, or HeyGen via Lambda
    • Store generated videos in S3
  • Amazon EventBridge
    • Schedule daily lesson generation
    • Content publishing workflows
    • Event-driven architecture

Payment & Monetization

  • Stripe Integration
    • Lambda functions for payment processing
    • Webhook handling via API Gateway → Lambda
    • Subscription management
    • Invoice generation
  • AWS Secrets Manager
    • Secure storage for Stripe keys
    • Rotation policies

Background Processing

  • AWS ECS Fargate (Small Service)
    • Long-running batch jobs
    • Video processing orchestration
    • Data exports and reporting
    • Scheduled tasks (ECS Scheduled Tasks)
  • Amazon SQS
    • Decouple heavy workloads
    • Dead letter queues for failed jobs
    • FIFO queues for ordered processing

Search & Analytics

  • Amazon OpenSearch Serverless
    • Course search and discovery
    • Aggregations (popular courses, categories)
    • Auto-scaling based on query load
    • No cluster management
  • Amazon QuickSight
    • Business analytics dashboard
    • Revenue reporting
    • User engagement metrics
    • Course completion rates

Monitoring & Observability

  • AWS CloudWatch
    • Unified logging (Lambda, AppSync, ECS)
    • Custom metrics and dashboards
    • Alarms for critical metrics
  • AWS X-Ray
    • End-to-end request tracing
    • AppSync → Lambda → Aurora tracing
    • Performance bottleneck identification
  • CloudWatch RUM (Real User Monitoring)
    • Frontend performance monitoring
    • User experience metrics

Email & Notifications

  • Amazon SES
    • Transactional emails
    • Email templates
    • Bounce and complaint handling
  • Amazon SNS
    • Push notifications (via Amplify)
    • SMS notifications
    • Multi-channel delivery
  • Amazon Pinpoint
    • Marketing campaigns
    • User segmentation
    • Course recommendation emails

CI/CD Pipeline

  • AWS Amplify Console
    • Automatic frontend deployments
    • Preview environments for PRs
  • AWS SAM or CDK
    • Infrastructure as Code
    • Deploy Lambda, AppSync, databases
    • Automated testing in pipeline
  • GitHub Actions / CodePipeline
    • Run tests, linting
    • Deploy backend infrastructure
    • Multi-stage deployments (dev, staging, prod)

Data Flow Examples

1. User Browses Courses (REST API) 

GET /courses?category=leadership&limit=20
Authorization: Bearer {jwt-token}
x-api-key: {api-key}

Response:
{
  "success": true,
  "data": [
    {
      "id": "course-123",
      "title": "Leadership Fundamentals",
      "description": "Build essential leadership skills",
      "category": "leadership",
      "durationDays": 14,
      "price": 29.99,
      "thumbnail": "https://cdn.example.com/thumb.jpg",
      "lessonsCount": 14
    }
  ]
}
  • User → CloudFront → Amplify Frontend → API Gateway → Lambda → Aurora Serverless → Response

2. Admin Creates Course with AI 

POST /ai-generation/generate-course
Authorization: Bearer {admin-jwt-token}
x-api-key: {api-key}

{
  "title": "Advanced React Patterns",
  "category": "programming",
  "durationDays": 21,
  "targetAudience": "Intermediate developers"
}

Response: { "success": true, "data": { "jobId": "job-456" } }

Flow:

  • Admin → API Gateway → Lambda (start-course-generation) → Step Functions → Bedrock (generate outline & lessons) + HeyGen (generate videos) → S3 (store assets) → Aurora (store course data) → Admin notification

3. User Enrolls in Course 

POST /enrollments
Authorization: Bearer {jwt-token}
x-api-key: {api-key}

{
  "courseId": "course-123"
}

Response:
{
  "success": true,
  "data": {
    "enrollmentId": "enroll-789",
    "courseId": "course-123",
    "userId": "user-001",
    "enrolledAt": "2025-12-11T10:00:00Z",
    "status": "active"
  }
}
  • Frontend → API Gateway → Lambda → Aurora (create enrollment) → SNS (confirmation email) → Response

4. Track Lesson Progress 

POST /progress
Authorization: Bearer {jwt-token}
x-api-key: {api-key}

{
  "lessonId": "lesson-42",
  "completed": true,
  "timeSpentSeconds": 300
}

Response:
{
  "success": true,
  "data": {
    "progressId": "prog-999",
    "lessonId": "lesson-42",
    "completed": true,
    "completedAt": "2025-12-11T10:05:00Z"
  }
}
  • Frontend → API Gateway → Lambda → Aurora → Update user statistics → Response
  • Note: Real-time updates achieved via polling (check progress every 30 seconds) or can be upgraded to WebSockets in future

REST API Endpoints

Course Management 

GET    /courses              - List all courses (with optional filters)
GET    /courses/{id}         - Get course details
POST   /courses              - Create course (admin only)
PUT    /courses/{id}         - Update course (admin only)
DELETE /courses/{id}         - Delete course (admin only)

Lesson Management 

GET    /lessons              - List lessons for a course
GET    /lessons/{id}         - Get lesson details
POST   /lessons              - Create lesson (admin only)
PUT    /lessons/{id}         - Update lesson (admin only)
DELETE /lessons/{id}         - Delete lesson (admin only)

Enrollment & Progress 

POST   /enrollments          - Enroll in a course
GET    /enrollments          - Get user's enrollments
POST   /progress             - Update lesson progress
GET    /progress/{userId}    - Get user progress for all courses

User Management 

GET    /users/{id}           - Get user profile
PUT    /users/{id}           - Update user profile
GET    /users/{id}/stats     - Get user statistics

Analytics & Reporting 

GET    /analytics/dashboard  - Get platform analytics (admin only)
GET    /analytics/course/{id} - Get course performance metrics

AI Content Generation 

POST   /ai-generation/generate-course     - Start course generation
GET    /ai-generation/jobs/{id}           - Get generation job status
POST   /ai-generation/generate-video      - Generate lesson video

Standard Response Format 

// Success response
{
  "success": true,
  "data": T  // The actual response data
}

// Error response
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}  // Optional additional error information
  }
}

Database Schema (Aurora PostgreSQL) 

-- Core tables
users (id, cognito_sub, email, name, role, created_at)
courses (id, title, description, category_id, duration_days, price, status, metadata JSONB)
categories (id, name, slug, description, icon_url)
lessons (id, course_id, day, title, content TEXT, video_url, action_items JSONB, resources JSONB)
enrollments (id, user_id, course_id, enrolled_at, completed_at, payment_id, stripe_subscription_id)
progress (id, user_id, lesson_id, completed, completed_at, time_spent_seconds)
payments (id, user_id, amount, currency, stripe_payment_id, status, metadata JSONB)

-- Indexes for performance
CREATE INDEX idx_courses_category ON courses(category_id);
CREATE INDEX idx_lessons_course ON lessons(course_id);
CREATE INDEX idx_progress_user_lesson ON progress(user_id, lesson_id);

Cost Optimization Strategies

  1. Aurora Serverless v2: Scales to zero during inactivity (pay-per-second billing)
  2. Lambda: Pay-per-use for API logic (no idle costs)
  3. Step Functions Express: 90% cheaper than standard workflows for AI generation
  4. API Gateway Caching: Cache GET responses to reduce Lambda invocations
  5. CloudFront Caching: Reduce origin requests and improve global performance
  6. S3 Intelligent-Tiering: Automatic storage class optimization
  7. OpenSearch Serverless: No cluster overhead (when implemented)
  8. ElastiCache Deferred: Provisioned but unused until needed (can be removed to save ~$50-90/month)

Scalability Features

  • API Gateway: Handles 10,000 requests/second (soft limit, can be increased to 100K+)
  • Aurora Serverless: Auto-scales from 0.5 to 128 ACUs based on load
  • Lambda: Concurrent execution up to 1,000 (default, adjustable to 100,000+)
  • Global distribution: CloudFront CDN for low-latency worldwide
  • Database scaling: Aurora read replicas can be added for heavy read workloads
  • Horizontal scaling: Stateless Lambda functions scale automatically

Estimated Monthly Cost (Scaling Scenario)

Low Traffic (0-5k users) - Current MVP

  • API Gateway: ~$3.50 (1M requests)
  • Lambda: ~$20-40
  • Aurora Serverless v2: ~$30-60 (0.5-2 ACU average)
  • S3 + CloudFront: ~$30-50
  • Cognito: Free tier covers 50k MAU
  • ElastiCache (if enabled): ~$50-90 (currently unused)
  • Total: ~$200-300/month

Medium Traffic (5k-50k users)

  • API Gateway: ~$35 (10M requests)
  • Lambda: ~$100-200
  • Aurora Serverless v2: ~$200-400 (2-8 ACU average)
  • S3 + CloudFront: ~$150-300
  • Cognito: ~$27.50 (50k MAU @ $0.0055)
  • ElastiCache: ~$100-150
  • Total: ~$650-1,200/month

Pros

  • ✅ Simple, proven REST API pattern (easy to learn and debug)
  • ✅ Standard HTTP tooling and debugging (Postman, curl, browser DevTools)
  • ✅ Strongly typed end-to-end with TypeScript
  • ✅ Cost-effective at low scale, scalable at high scale
  • ✅ Flexible scaling (serverless + containers for batch jobs)
  • ✅ Fast development velocity
  • ✅ Excellent caching support (API Gateway + CloudFront)
  • ✅ Native AWS service integration (no third-party dependencies)
  • ✅ Lower operational complexity than GraphQL
  • ✅ Easier to monitor and trace (CloudWatch + X-Ray)

Cons

  • ❌ No built-in real-time subscriptions (requires polling or future WebSocket implementation)
  • ❌ Potential for over-fetching data (clients get full response objects)
  • ❌ Multiple endpoints instead of single API endpoint
  • ❌ Some vendor lock-in (Aurora Serverless, API Gateway)
  • ❌ Aurora Serverless can be expensive at very high scale vs provisioned instances
  • ❌ Requires careful API versioning for breaking changes

Best For

  • MVP and early-stage applications
  • Teams familiar with REST API patterns
  • Applications where real-time features are not critical
  • Projects requiring simple debugging and monitoring
  • Rapid development with proven patterns
  • Startups that need to move fast without GraphQL learning curve
  • Applications with straightforward CRUD operations

Migration Path

This architecture is designed to evolve:

  1. Start (Current MVP): REST API Gateway + Lambda + Aurora Serverless (0.5-16 ACU)
  2. Grow (5K-50K users):
    • Enable ElastiCache for frequently accessed data
    • Add Aurora read replicas for heavy read workloads
    • Implement API Gateway caching for GET endpoints
  3. Scale (50K-500K users):
    • Migrate Aurora to provisioned instances for cost optimization
    • Add regional CloudFront distributions
    • Implement database connection pooling
  4. Advanced (500K+ users):
    • Consider GraphQL/AppSync for real-time features (hybrid approach)
    • Multi-region Aurora with global database
    • Advanced caching strategies (multiple layers)
    • Consider microservices split if needed

Back to top

Momentum LMS © 2025. Distributed under the MIT license.