5.7 KiB
Below is the clean Markdown (.md) version of the architecture, ready to copy directly into a file like learning-platform-architecture.md.
⸻
Learning Platform System Architecture
Admin & Learner Content Management, Video (Vimeo), Assessment & Progress Tracking
1. Architecture Overview
Architecture Style
Modular Monolith (MVP-ready, Microservices-friendly)
This approach enables:
- Fast MVP delivery
- Clear separation of responsibilities
- Easy future extraction into microservices (Assessment, Video, Analytics)
Admin Web / Mobile App ↓ API Gateway / BFF ↓ Core Application Services ↓ Domain Modules ↓ Databases & External Integrations
2. Client Layer
2.1 Admin Panel (Web)
Responsibilities
- Program, Course, Module creation
- Video upload & Vimeo integration
- Assessment & practice creation
- Publishing workflows
- Analytics & reporting
Consumes
- Secured Admin APIs
- Role-based access control
2.2 Learner App (Mobile / Web)
Responsibilities
- Fetch courses and modules
- Watch videos (Vimeo player)
- Take assessments & practices
- Track and resume learning progress
Consumes
- Read-optimized Learner APIs
3. API Gateway / Backend-for-Frontend (BFF)
Purpose
- Separate Admin and Learner concerns
- Aggregate responses
- Enforce security and versioning
Endpoints
/api/admin/* /api/learner/*
Capabilities
- Authentication & authorization
- Rate limiting
- API versioning
- Response aggregation (content + progress)
4. Core Domain Modules
4.1 Content Structure Module (Foundation)
Defines the learning hierarchy and core relationships.
Learning Hierarchy
Program └── Course └── Module ├── Video └── Assessment
Core Entities
Program
id name description level (Beginner | Intermediate | Advanced) metadata (JSON) status (draft | published)
Course
id program_id name CEFR_level order metadata (JSON) status
Module
id course_id title order metadata (JSON) status
Why metadata (JSON)?
- Allows future parameters without database migrations
- Examples: difficulty, tags, AI flags, localization, prerequisites
4.2 Video Module (Vimeo Integrated)
Responsibilities
- Store video metadata
- Integrate with Vimeo
- Track watch progress
- Enforce publishing dependencies
Video Entity
id module_id title description order vimeo_video_id duration thumbnail_url status (draft | published) metadata (JSON)
Vimeo Integration Flow
- Admin uploads video
- Backend uploads to Vimeo
- Store Vimeo metadata:
- video ID
- duration
- thumbnails
- Listen to Vimeo webhooks:
- video.processed
- video.deleted
Publishing Rule
- An assessment linked to a video cannot be published unless the video is published
4.3 Assessment & Practice Module (Isolated)
This module is fully decoupled from videos and modules.
Why Isolation?
- Supports course-level, module-level, and video-level practices
- Enables future AI grading and certification
- Allows independent scaling
Assessment Entities
Assessment
id scope_type (PROGRAM | COURSE | MODULE | VIDEO) scope_id title assessment_type (speaking | mcq | listening | mock_test) status (draft | published) metadata (JSON)
Question
id assessment_id type (text | voice | mcq) prompt sample_answer tips order metadata (JSON)
Persona
id name voice avatar metadata (JSON)
Flexible Linking
Assessments can be attached to:
- Entire courses
- Specific modules
- Individual videos
4.4 Progress Tracking Module
Tracks all learner activity without modifying content logic.
Responsibilities
- Video progress tracking
- Assessment attempts
- Completion states
- Resume learning
Progress Entities
User Content Progress
user_id content_type (PROGRAM | COURSE | MODULE) content_id progress_percentage status (not_started | in_progress | completed)
User Video Progress
user_id video_id watched_seconds completion_percentage completed_at
User Assessment Progress
user_id assessment_id attempt_no score feedback completed_at
Supports
- Resume playback
- Lock/unlock content
- Accurate dashboards
5. Publishing & Dependency Rules Engine
A configurable rule-based system.
Examples
- Course cannot be published without published modules
- Module cannot be published without at least one published video
- Assessment cannot be published if linked video is draft
Rule Model
entity_type condition error_message
6. Analytics & Reporting Module
Analytics consume events, not business logic.
Events
- video.started
- video.completed
- assessment.started
- assessment.completed
- course.completed
Stored in:
- Analytics database
- Event stream (Kafka-ready)
7. Data Layer
Recommended Stack
- PostgreSQL – relational core data
- Redis – progress caching & resume states
- Object Storage – thumbnails, audio prompts
8. Security & Roles
Roles
Admin Content Manager Instructor Learner
Enforcement
- API-level authorization
- Draft vs published access rules
9. Extensibility & Future Readiness
This architecture supports:
- AI scoring & feedback
- New assessment types
- Certificates
- Offline sync
- Multiple video providers (Vimeo → AWS IVS)
Without refactoring core modules.
10. Roadmap
MVP Scope
- Programs, Courses, Modules
- Vimeo videos
- Assessments & practices
- Progress tracking
- Admin publishing rules
Phase 2
- AI-driven personalization
- Adaptive learning paths
- Gamification
- Certification engine
Architectural Principle
Clear separation between:
- Content
- Video
- Assessment
- Progress
- Analytics
Ensuring scalability, maintainability, and rapid feature expansion.