Course - API & Integration Guide

Audience: Superadmin panel developers, mobile/web frontend developers, and backend integrators. Scope: Admin APIs, customer/mobile APIs, public verification API, DTO contracts, enums, flows, errors, and integration recipes.

1. How to Read / Quick Metadata

• Module: Course
• Owners: API Platform + Content/LMS team
• Environments: dev, staging, prod
• Auth models:
  • Admin routes: Admin JWT + RoleGuard + @Permissions
  • Customer routes: User JWT
  • Public verify route: no auth
• Base URLs:
  • Admin: /api/admin/courses/*, /api/admin/certificates/*
  • Customer: /api/courses/*
  • Mobile-composed customer: /api/mobile/courses/*
  • Public: /api/certificates/*
• Swagger groups (current):
  • Admin: Course Management (Admin), Course Topics (Admin), Course Lessons (Admin), Course Quiz (Admin), Course Resources (Admin), Course Reviews (Admin), Course Certificates (Admin)
  • Mobile/customer: Course Discovery (Mobile), Course Purchases (Mobile), Course Learning (Mobile), Course Quiz (Mobile), Course Certificates (Mobile)

2. High-Level Overview

Course module provides LMS runtime on top of digital commerce entitlement (product_access).

Responsibilities:

• expose publish-ready course discovery and detail views,
• serve purchased curriculum/lesson runtime and progress updates,
• enforce quiz rules (eligibility, attempts, scoring, result retrieval),
• generate and expose course completion certificates,
• provide complete admin surface for course, curriculum, review, quiz, and certificate template management.

System fit:

• Catalog/Order integration: a course is linked to a product (productType="course") and access is controlled by order/payment-created product_access.
• Tag/featured integration: course discovery filters tags through shared product_tag and featured lists through shared featured_product.
• Async integration: certificate generation is queued through BullMQ (QueueName.COURSES, CourseJob.GENERATE_CERTIFICATE).
• Cache integration: list/detail endpoints are Redis-cached with deterministic keys built via CacheKeyUtil.

3. Core Concepts & Terminology

• Course: sellable learning product with publishing lifecycle and optional quiz/certificate switches.
• Topic: ordered grouping of lessons in a course.
• Lesson: ordered learning unit (video/live/text/file/link).
• Resource: downloadable/link asset scoped to course, optionally to topic or lesson.
• Progress: user completion state by lesson.
• Quiz: per-course assessment definition (attempt cap, pass mark, time limit).
• Quiz Attempt: single user attempt containing answers + score + pass/fail.
• Certificate Template: rendering template metadata for certificate generation.
• User Certificate: issued certificate record for (userId, courseId).
• Access Validity: admin-configured course.accessValidityDays controls purchase access duration. null = lifetime access. On repurchase, active access is extended (accessEndAt = existing.accessEndAt + validityDays).

Key lifecycle flags:

• course.status: draft -> published -> hidden -> archived
• course.reviewMode: real | mocked | disabled
• course.quizEnabled: toggles quiz gate
• course.certificateEnabled: toggles certificate eligibility
• course.accessValidityDays: null = lifetime, positive integer = days of access from purchase date

Schema guardrails:

• certificate_template.name is globally unique (certificate_template_name_unique)
• course.access_validity_days is constrained to null or a positive integer (course_access_validity_days_positive_check)
• template creates are idempotent on full payload match; same name with different payload is rejected

Eligibility chain (certificate):

1. certificate enabled on course
2. user entitlement exists and is not expired
3. all enabled lessons completed
4. if quiz enabled, at least one passed completed attempt exists

4. Architecture & Data Flow

4.1 Module Interaction Diagram

4.2 Certificate Generation Runtime Flow

5. API Surface Summary

All customer routes are also mounted under /api/mobile/courses/* via mobile.module.ts composition.

5.1 Swagger Group to Path Mapping

6. Data Models & Enums

6.1 Key Response DTOs

CourseListItemDto

Used in: GET /api/courses, GET /api/admin/courses

{
  "id": 101,
  "title": "Complete Stock Market Trading Course",
  "slug": "complete-stock-market-trading-course",
  "shortSummary": "Learn market structure and risk management.",
  "status": "published",
  "isSellable": true,
  "categoryId": 3
}

CurriculumResponseDto

Used in: GET /api/courses/:courseId/curriculum

{
  "courseId": 101,
  "courseTitle": "Complete Stock Market Trading Course",
  "topics": [
    {
      "id": 5,
      "title": "Introduction",
      "description": "Core market fundamentals.",
      "orderIndex": 1,
      "lessons": [
        {
          "id": 11,
          "title": "What is NEPSE?",
          "lessonType": "video",
          "duration": 15,
          "orderIndex": 1,
          "isPreview": false,
          "isCompleted": true
        }
      ]
    }
  ],
  "totalLessons": 3,
  "completedLessons": 1,
  "progressPercent": 33.33
}

QuizDetailResponseDto

Used in: GET /api/courses/:courseId/quiz

{
  "id": 12,
  "courseId": 101,
  "title": "Module 1 Final Assessment",
  "description": "Complete this quiz to unlock certificate eligibility.",
  "quizAttempts": 3,
  "passMark": 60,
  "timeLimit": 30,
  "shuffleQuestions": false,
  "showResults": true,
  "isEligible": true,
  "notEligibleReason": null,
  "totalAttempts": 1,
  "remainingAttempts": 2,
  "hasInProgressAttempt": false,
  "lastAttempt": {
    "attemptId": 88,
    "score": 7,
    "passed": true,
    "completedAt": "2026-03-19T10:20:00.000Z"
  }
}

SubmitQuizDto (request)

Used in: POST /api/courses/:courseId/quiz/attempt/:attemptId/submit

{
  "answers": {
    "44": "Market Order",
    "45": "true",
    "46": ["bull", "bullish"]
  }
}

CertificateGenerationResponseDto

Used in: POST /api/courses/:courseId/certificate/generate

{
  "status": "queued",
  "message": "Certificate generation has been queued successfully."
}

CertificateVerifyResponseDto

Used in: GET /api/certificates/verify/:certificateNumber

{
  "isValid": true,
  "studentName": "Jane Doe",
  "courseName": "Complete Stock Market Trading",
  "issuedAt": "2026-03-19T10:00:00.000Z",
  "certificateNumber": "CERT-20260319-384726"
}

6.2 Important Request DTOs (Admin)

• CreateCourseDto / UpdateCourseDto
• CreateTopicDto / UpdateTopicDto / ReorderTopicsDto
• CreateLessonDto / UpdateLessonDto / ReorderLessonsDto
• CreateResourceDto
• CreateReviewDto / UpdateReviewDto / FetchReviewDto
• CreateQuizDto / UpdateQuizDto
• CreateQuestionDto / UpdateQuestionDto / ReorderQuestionsDto
• CreateCertificateTemplateDto / UpdateCertificateTemplateDto
• FetchCourseDto, FetchCertificateTemplateDto, FetchCertificateDto

6.3 Enums

course_status

course_lesson_type

course_review_mode

resource_type

quiz_question_type

Eligibility reason enums

certificate.notEligibleReason values:

• certificate_not_enabled
• not_enrolled
• access_expired
• course_incomplete
• quiz_not_passed
• null

quiz.notEligibleReason values:

• course_not_complete
• max_attempts_reached
• null

7. Endpoint Reference + Payload Cheatsheet (All APIs)

7.1 Common Auth and Response Wrapper

• Response wrapper follows ResponseDto<T>:
  • success payload in data
  • paginated list metadata only when pagination enabled
• Pagination normalization uses PaginationUtil.normalize({ pagination, page, size })
• Rate limit key pattern:
  • Admin: rl:courses:admin:action:<action>-key:<clientKey>
  • Customer: rl:courses:customer:action:<action>-key:<clientKey>
  • Public verify: rl:certificates:public:action:cert-verify-key:<clientKey>

7.2 Payload Cheatsheet Table (Every Endpoint)

7.2.1 Quiz Question Update Contract

For PATCH /api/admin/courses/:courseId/quiz/questions/:questionId:

• If you update options, include correctAnswer in the same payload.
• If you update questionType, include compatible correctAnswer (and options where required) in the same payload.
• multiple_choice: correctAnswer must be a string and exactly match one option.
• true_false: options must resolve to ["true", "false"] and correctAnswer must be "true" or "false".
• short_answer: correctAnswer can be string or string[]; options should be omitted or null.

Example:

{
  "options": ["Market Order", "Limit Order", "Stop Loss"],
  "correctAnswer": "Market Order",
  "explanation": null
}

7.3 Error Codes

8. Common Flows / Recipes and Client Integration Guidelines

8.1 Admin Flow: Build Publishable Course

1. POST /api/admin/courses
2. POST /api/admin/courses/:courseId/topics
3. POST /api/admin/courses/:courseId/topics/:topicId/lessons
4. Optional: add resources/reviews/quiz/template
5. PATCH /api/admin/courses/:id with status="published", isSellable=true
6. verify in customer listing via /api/courses

8.2 Mobile Flow: Learn + Quiz + Certificate

1. List purchases: GET /api/mobile/courses/purchases
2. Open curriculum: GET /api/mobile/courses/:courseId/curriculum
3. Mark lessons complete per lesson
4. Open quiz detail and start/submit attempt
5. Check eligibility
6. Generate certificate (queue)
7. Fetch certificate detail/list and show download URL when available

8.3 Public Verification Flow

1. Input certificate number
2. GET /api/certificates/verify/:certificateNumber
3. If isValid=false, show invalid state
4. If isValid=true, render student/course/date summary

8.4 Mobile App

• Keep learner state machine explicit:
  • not_purchased -> learning -> quiz_pending -> certificate_pending -> certified
• Polling strategy for certificate generation:
  • after status=queued, poll GET /certificate with exponential backoff
• Respect rate limits; centralize 429 handling and retry with jitter.
• Cache recommendations:
  • /courses list and /courses/:slug detail can be cached client-side for short TTL
  • avoid long-lived cache for progress/quiz attempts/certificate status
• Suggested screen mapping:
  • Discover screen: /courses
  • Course detail: /courses/:slug
  • My learning: purchases + curriculum + progress
  • Quiz screen: quiz detail/start/submit/attempts
  • Certificate screen: eligibility/generate/detail/list

8.5 Superadmin Panel

• Course editor should split tabs: Course Info, Curriculum, Resources, Reviews, Quiz, Certificate Template.
• Lock destructive actions when status is archived unless explicit restore workflow exists.
• For reorder APIs, always submit complete ordered ID arrays (not partial reorder deltas).
• Use list filters directly via query DTO fields (status/category/review flags/sort/order).

9. Validation Rules & Edge Cases

Course runtime depends on both content structure and commerce entitlement. The most common integration bug is treating a published course as automatically accessible; it is not. Learning and certificate routes require valid product_access, and expired access returns forbidden even if progress exists. Slug-based discovery accepts historical slugs, but only for currently published and isSellable=true courses; hidden/archived records are not exposed. Quiz behavior has strict guardrails: users cannot start until course completion, cannot exceed configured attempt count, cannot submit an already completed attempt, and cannot submit after the time limit. Certificate generation is intentionally asynchronous and idempotent: repeated generate calls for the same (userId, courseId) use deterministic BullMQ jobId dedupe and DB conflict-safe insert semantics. Public verification intentionally never throws not-found; it returns isValid=false to keep verifier UX simple. For admin mutations, ordering arrays must be complete and unique, and lesson/resource payloads must match their type-specific requirements (videoAssetRef, fileRef, linkUrl, etc.).

10. Testing, Sandbox & Example Scenarios

10.1 Suggested Test Scenarios

• Admin creates full course, publishes it, and course appears in customer list.
• Course slug changed in admin; old slug still resolves to canonical detail.
• User without entitlement hits curriculum/quiz/certificate endpoints and receives 403.
• User completes all lessons then can start quiz; before completion receives 400.
• User reaches max quiz attempts and receives 400 Maximum quiz attempts reached.
• User submits after time limit and receives 400 Time limit exceeded.
• Certificate generate queues exactly one job for same (userId, courseId) via deterministic job id.
• Public verification returns isValid=false for unknown certificate number.
• 429 behavior for admin/customer/public route families with sliding window Redis keys.

10.2 Example Seed Data

{
  "course": {
    "id": 101,
    "title": "Complete Stock Market Trading Course",
    "status": "published",
    "isSellable": true,
    "quizEnabled": true,
    "certificateEnabled": true
  },
  "quiz": {
    "quizAttempts": 3,
    "passMark": 60,
    "timeLimit": 30,
    "questions": 20
  },
  "user": {
    "id": "4f0f5f62-4f79-4d5b-a5d9-7f71a5f89d27",
    "hasProductAccess": true,
    "courseCompleted": true,
    "passedQuiz": true
  },
  "certificate": {
    "certificateNumber": "CERT-20260319-384726"
  }
}

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

See Also

• Feature Guide: See Course - Feature List Section 6 (State Models) for course and lesson lifecycle diagrams.
• Backend Reference: See Course - Backend Documentation Section 9 for system architecture diagram.