Yimaru-Architecture/course_hierarchy.md

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.