Yimaru-BackEnd/README.md

# 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 Course Sub-categories

Course Category
└── Course Sub-categories[]

2. Course Sub-category

Table: course_sub_categories

Purpose:
A grouping within a category (e.g., Speaking, Listening under Learning English).

Key Fields:

category_id – FK → course_categories.id

title, description

is_active

Relationships:

Belongs to one Course Category

Has many Courses

Course Category
└── Course Sub-category
    └── Courses[]

3. Course

Table: courses

Purpose:
A learning unit within a sub-category representing different skill levels
(e.g., Beginner, Intermediate, Advanced).

Key Fields:

sub_category_id – FK → course_sub_categories.id

title, description

thumbnail

display_order

level – BEGINNER | INTERMEDIATE | ADVANCED

is_active

Relationships:

Belongs to one Course Sub-category

Has many Course Videos

Has many Practices

Course Sub-category
└── Course
    ├── Course Videos[]
    └── Practices[]

4. Course Video

Table: course_videos

Purpose:
Video learning content attached to a course.

Key Fields:

course_id – FK → courses.id

title, description

video_url

duration, resolution

Publishing controls:

is_published

publish_date

visibility

instructor_id

thumbnail

display_order

is_active

Relationships:

Belongs to one Course

Course
└── Course Video

5. Practice

Table: practices

Purpose:
Exercises or assessments that belong to a course.

Key Fields:

course_id – FK → courses.id

title, description

banner_image

persona

is_active

Relationships:

Belongs to one Course

One Practice → Many Practice Questions

Course
└── Practice
    └── Practice Questions[]

6. Practice Question

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 Sub-category
    └── Course (with levels: BEGINNER, INTERMEDIATE, ADVANCED)
        ├── Course Video
        └── Practice
            └── Practice Question

Architectural Observations

Simple three-level hierarchy: Category → Sub-category → Course

Level is now a property of Course, not a separate entity

Cascade deletes ensure referential integrity

Schema is well-suited for:

LMS platforms

Progressive learning apps

Video + assessment-based education systems