-

course_hierarchy.md

@@ -0,0 +1,365 @@
+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
+1. Admin uploads video
+2. Backend uploads to Vimeo
+3. Store Vimeo metadata:
+   - video ID
+   - duration
+   - thumbnails
+4. 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.