Yimaru/Yimaru-Architecture
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b42ce3ef82
Yimaru-Architecture/course_hierarchy.md
“kirukib” b42ce3ef82 -
2026-01-19 01:48:09 +03:00

5.7 KiB
Raw Blame History

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.