# 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