356 lines
7.1 KiB
Markdown
356 lines
7.1 KiB
Markdown
# Yimaru Backend
|
||
|
||
Yimaru Backend is the server-side application that powers the Yimaru online learning system. It manages courses, lessons, quizzes, student progress, instructor content, and administrative operations for institutions and users on the platform.
|
||
|
||
## Table of Contents
|
||
|
||
- [Installation](#installation)
|
||
- [Environment Configuration](#environment-configuration)
|
||
- [Running the Application](#running-the-application)
|
||
- [Database Management](#database-management)
|
||
- [Testing and Code Quality](#testing-and-code-quality)
|
||
- [API Documentation](#api-documentation)
|
||
- [Project Structure](#project-structure)
|
||
- [Core Services Overview](#core-services-overview)
|
||
- [Roles and Access Control](#roles-and-access-control)
|
||
- [Code Organization Guidelines](#code-organization-guidelines)
|
||
- [Further Details](#further-details)
|
||
|
||
---
|
||
|
||
## Installation
|
||
Before running the application, ensure you have the following installed:
|
||
|
||
- [Go](https://golang.org/doc/install) (1.20+ recommended)
|
||
- [Docker](https://www.docker.com/)
|
||
- [Air](https://github.com/cosmtrek/air) — for live reloading during development
|
||
- [SQLC](https://sqlc.dev)
|
||
- [Migrate](https://github.com/golang-migrate/migrate)
|
||
- [Swag](https://github.com/swaggo/swag)
|
||
|
||
Clone the repository:
|
||
|
||
```bash
|
||
git clone https://github.com/your-org/Yimaru-backend.git
|
||
cd Yimaru-backend
|
||
|
||
├── cmd/
|
||
│ └── main.go # Application entry point
|
||
├── internal/
|
||
│ ├── config/ # Configuration and environment loading
|
||
│ │ └── config.go
|
||
│ ├── domain/ # Domain models, constants, and roles
|
||
│ │ ├── course.go # Course and lesson structures
|
||
│ │ └── roles.go # Role definitions (e.g., RoleAdmin, RoleInstructor)
|
||
│ ├── repository/ # Database interaction layer
|
||
│ │ ├── course.go # Course-related queries
|
||
│ │ ├── lesson.go # Lesson-related database functions
|
||
│ │ ├── user.go # User repository methods
|
||
│ │ └── ... # Other repository files
|
||
│ ├── services/ # Business logic and core services
|
||
│ │ ├── course/
|
||
│ │ │ └── service.go # Course management logic
|
||
│ │ └── quiz/
|
||
│ │ ├── service.go # Quiz management and evaluation logic
|
||
│ │ └── eval.go # Evaluation logic for student progress
|
||
│ └── web_server/ # HTTP handlers, routes, middleware, and cron jobs
|
||
│ ├── cron.go # Scheduled background tasks
|
||
│ └── handlers/
|
||
│ ├── course_handler.go # Course-related API endpoints
|
||
│ ├── user_handler.go # User-related endpoints
|
||
│ └── ... # Additional handlers
|
||
├── db/
|
||
│ └── migrations/ # SQL migration files
|
||
├── docs/
|
||
│ ├── swagger/ # Swagger/OpenAPI documentation files
|
||
│ └── docs.go # Swaggo-generated docs
|
||
├── gen/
|
||
│ └── db/ # SQLC-generated Go code for database access
|
||
├── makefile # Development and operations commands
|
||
├── .env # Environment configuration file
|
||
└── README.md # Project documentation
|
||
|
||
|
||
1. Course Category (Top-Level Classification)
|
||
|
||
Table: course_categories
|
||
|
||
Purpose:
|
||
Logical grouping of courses (e.g., Learning English, Other Courses).
|
||
|
||
Key Fields:
|
||
|
||
id – Primary identifier
|
||
|
||
name – Category name
|
||
|
||
is_active – Soft enable/disable
|
||
|
||
created_at – Audit timestamp
|
||
|
||
Relationships:
|
||
|
||
One Course Category → Many Courses
|
||
|
||
Course Category
|
||
└── Courses[]
|
||
|
||
2. Course
|
||
|
||
Table: courses
|
||
|
||
Purpose:
|
||
Represents a full course offering under a category.
|
||
|
||
Key Fields:
|
||
|
||
category_id – FK → course_categories.id
|
||
|
||
title, description
|
||
|
||
is_active
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Course Category
|
||
|
||
Has many Programs
|
||
|
||
Course Category
|
||
└── Course
|
||
└── Programs[]
|
||
|
||
3. Program
|
||
|
||
Table: programs
|
||
|
||
Purpose:
|
||
A structured learning track or syllabus within a course
|
||
(e.g., Beginner Track, Advanced Track).
|
||
|
||
Key Fields:
|
||
|
||
course_id – FK → courses.id
|
||
|
||
title, description
|
||
|
||
thumbnail
|
||
|
||
display_order
|
||
|
||
is_active
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Course
|
||
|
||
Has many Levels
|
||
|
||
Course
|
||
└── Program
|
||
└── Levels[]
|
||
|
||
4. Level
|
||
|
||
Table: levels
|
||
|
||
Purpose:
|
||
Represents a progression stage inside a program (Level 1, Level 2, etc.).
|
||
|
||
Key Fields:
|
||
|
||
program_id – FK → programs.id
|
||
|
||
title, description
|
||
|
||
level_index
|
||
|
||
Aggregates:
|
||
|
||
number_of_modules
|
||
|
||
number_of_practices
|
||
|
||
number_of_videos
|
||
|
||
is_active
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Program
|
||
|
||
Has many Modules
|
||
|
||
Can directly own Practices
|
||
|
||
Program
|
||
└── Level
|
||
├── Modules[]
|
||
└── Practices[] (owner_type = LEVEL)
|
||
|
||
5. Module
|
||
|
||
Table: modules
|
||
|
||
Purpose:
|
||
A lesson or unit inside a level.
|
||
|
||
Key Fields:
|
||
|
||
level_id – FK → levels.id
|
||
|
||
title
|
||
|
||
content
|
||
|
||
display_order
|
||
|
||
is_active
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Level
|
||
|
||
Has many Videos
|
||
|
||
Can directly own Practices
|
||
|
||
Level
|
||
└── Module
|
||
├── Module Videos[]
|
||
└── Practices[] (owner_type = MODULE)
|
||
|
||
6. Module Video
|
||
|
||
Table: module_videos
|
||
|
||
Purpose:
|
||
Actual video learning content attached to a module.
|
||
|
||
Key Fields:
|
||
|
||
module_id – FK → modules.id
|
||
|
||
title, description
|
||
|
||
video_url
|
||
|
||
duration, resolution
|
||
|
||
Publishing controls:
|
||
|
||
is_published
|
||
|
||
publish_date
|
||
|
||
visibility
|
||
|
||
instructor_id
|
||
|
||
thumbnail
|
||
|
||
is_active
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Module
|
||
|
||
Module
|
||
└── Module Video
|
||
|
||
7. Practice (Polymorphic Ownership)
|
||
|
||
Table: practices
|
||
|
||
Purpose:
|
||
Exercises or assessments that can belong to either a Level or a Module.
|
||
|
||
Key Fields:
|
||
|
||
owner_type – LEVEL | MODULE
|
||
|
||
owner_id – ID of level or module
|
||
|
||
title, description
|
||
|
||
banner_image
|
||
|
||
persona
|
||
|
||
is_active
|
||
|
||
Constraint:
|
||
|
||
Enforced by CHECK (owner_type IN ('LEVEL', 'MODULE'))
|
||
|
||
Ownership enforced at the application layer
|
||
|
||
Relationships:
|
||
|
||
One Practice → Many Practice Questions
|
||
|
||
Level or Module
|
||
└── Practice
|
||
└── Practice Questions[]
|
||
|
||
8. Practice Question (Lowest Level)
|
||
|
||
Table: practice_questions
|
||
|
||
Purpose:
|
||
Individual questions within a practice session.
|
||
|
||
Key Fields:
|
||
|
||
practice_id – FK → practices.id
|
||
|
||
question
|
||
|
||
Voice support:
|
||
|
||
question_voice_prompt
|
||
|
||
sample_answer_voice_prompt
|
||
|
||
sample_answer
|
||
|
||
tips
|
||
|
||
type – MCQ | TRUE_FALSE | SHORT
|
||
|
||
Relationships:
|
||
|
||
Belongs to one Practice
|
||
|
||
Practice
|
||
└── Practice Question
|
||
|
||
Complete Hierarchical Flow (Compact View)
|
||
Course Category
|
||
└── Course
|
||
└── Program
|
||
└── Level
|
||
├── Module
|
||
│ ├── Module Video
|
||
│ └── Practice (MODULE)
|
||
│ └── Practice Question
|
||
└── Practice (LEVEL)
|
||
└── Practice Question
|
||
|
||
Architectural Observations
|
||
|
||
Strict top-down hierarchy until Level
|
||
|
||
Polymorphic design for practices allows reuse without table duplication
|
||
|
||
Cascade deletes ensure referential integrity
|
||
|
||
Aggregated counters in levels support fast analytics and UI summaries
|
||
|
||
Schema is well-suited for:
|
||
|
||
LMS platforms
|
||
|
||
Progressive learning apps
|
||
|
||
Video + assessment-based education systems |