HocTapAZ Docs

Appearance

Course Service API ​

Current Endpoints ​

  • GET /healthz
  • GET /readyz
  • GET /v1
  • PUT /v1/courses/{courseId}/snapshot
  • GET /v1/courses
  • POST /v1/courses
  • GET /v1/courses/{courseId}
  • PATCH /v1/courses/{courseId}
  • DELETE /v1/courses/{courseId}
  • GET /v1/courses/{courseId}/sections
  • POST /v1/courses/{courseId}/sections
  • PATCH /v1/courses/{courseId}/sections/{sectionId}
  • DELETE /v1/courses/{courseId}/sections/{sectionId}
  • GET /v1/courses/{courseId}/lessons
  • POST /v1/courses/{courseId}/lessons
  • GET /v1/courses/{courseId}/lessons/{lessonId}
  • PATCH /v1/courses/{courseId}/lessons/{lessonId}
  • DELETE /v1/courses/{courseId}/lessons/{lessonId}
  • POST /v1/courses/{courseId}/lessons/{lessonId}/video
  • DELETE /v1/courses/{courseId}/lessons/{lessonId}/video
  • GET /v1/courses/{courseId}/materials
  • POST /v1/courses/{courseId}/materials
  • GET /v1/courses/{courseId}/materials/{materialId}
  • PATCH /v1/courses/{courseId}/materials/{materialId}
  • DELETE /v1/courses/{courseId}/materials/{materialId}
  • GET /v1/courses/{courseId}/enrollments
  • POST /v1/courses/{courseId}/enrollments
  • PATCH /v1/courses/{courseId}/enrollments/{studentId}
  • DELETE /v1/courses/{courseId}/enrollments/{studentId}
  • GET /v1/student/courses
  • GET /v1/student/courses/{courseId}
  • POST /v1/student/courses/{courseId}/lessons/{lessonId}/progress
  • POST /v1/student/courses/{courseId}/lessons/{lessonId}/video-progress
  • POST /v1/student/courses/{courseId}/materials/{materialId}/view
  • GET /v1/public/courses
  • GET /v1/public/courses/{slug}

Native Course Foundation ​

Phase 8 course-service starts with course catalog records, sections, lessons, material metadata, enrollments, and basic student progress. This is an internal /v1 foundation, not a public /api/courses*, /api/student/courses*, or /api/public/catalog* cutover.

Legacy evidence:

  • apps/api/src/modules/courses/courses.controller.ts:42-334 maps teacher/admin course CRUD, section, lesson, video, material, enrollment, question, quiz, and report routes.
  • apps/api/src/modules/courses/courses.controller.ts:336-386 maps student course list/detail/mastery/recommendation/purchase/progress routes.
  • apps/api/src/modules/courses/courses.service.ts:23-169 delegates course routes to AppDataService and wallet purchase.
  • apps/api/src/modules/app-data/app-data.courses-support.ts:41-160 defines manager checks, active enrollment checks, topic validation, and response expansion.
  • apps/api/src/modules/app-data/app-data.courses-catalog.ts:41-262 implements legacy course list/detail/create/update/archive and section CRUD.
  • apps/api/src/modules/app-data/app-data.courses-lessons.ts:41-477 implements lesson/material CRUD, video metadata attachment, and cleanup behavior.
  • apps/api/src/modules/app-data/app-data.courses-enrollment.ts:41-475 implements enrollment CRUD, student course projection, lesson progress, video progress, and material views.
  • apps/api/src/modules/app-data/app-data.courses-assessment.ts:41-708 implements question links, quizzes, report, mastery, and recommendation; these are deferred from P8-005.
  • apps/api/src/modules/app-data/app-data.courses-files.ts:41-119 implements video/material content file access; streaming remains document-service/gateway work.
  • apps/api/src/modules/app-data/app-data.public.ts:19-392 exposes public course home/catalog/detail projections.
  • apps/api/prisma/schema.prisma:920-1188 defines Course, CourseSection, CourseLesson, CourseMaterial, CourseEnrollment, progress/view tables, question links, and quizzes.
  • packages/shared/src/index.ts:1278-1379 defines course, section, lesson, material, enrollment, and progress validation schemas.
  • apps/web/components/course/course-crud-client.tsx:52-307 consumes teacher/admin course CRUD, status, archive, and report routes.
  • apps/web/components/course/course-management-client.tsx:108-316 consumes course detail, sections, lessons, materials, video, question links, quizzes, and enrollments.
  • apps/web/components/course/student-course-client.tsx:131-170 consumes student course detail, recommendation, lesson/video progress, and material views.

Native contract:

  • PUT /v1/courses/{courseId}/snapshot upserts service-owned course data from legacy backfill, including nested sections, lessons, materials, and enrollments when supplied.
  • GET /v1/courses supports q, status, organizationId, instructorId, subjectId, visibility, page, and limit; X-Actor-Id/X-Actor-Role scopes non-admin reads.
  • POST /v1/courses creates a course with status DRAFT by default. Teachers default to themselves as instructor; admins must provide an instructor id until user-service adapters can choose a fallback.
  • GET/PATCH/DELETE /v1/courses/{courseId} preserve detail, partial update, and archive semantics. Delete sets status=ARCHIVED and clears featuredAt.
  • Section routes preserve course-scoped create/update/delete and orderIndex ordering.
  • Lesson routes preserve course-scoped create/update/delete, optional section/topic ids, preview, published to publishedAt, content fields, video metadata, and deletion cleanup of lesson-owned materials/progress.
  • Material routes preserve metadata CRUD, optional lesson binding, preview, published to publishedAt, and deletion cleanup of material views. File bytes remain document-service/object-storage work.
  • Enrollment routes preserve upsert by (courseId,studentId), status, paid amount, expiration, grant actor, and note.
  • Student course routes preserve active enrollment checks, published-course requirement, published lesson/material filtering, lesson progress status derivation, video progress auto-completing lessons at 95 percent, and material view increments.
  • Public course routes expose published/public/slugged course projections for gateway adapters.

Authorization model:

  • Native service accepts X-Actor-Id, X-Actor-Role, and X-Organization-Id; gateway remains responsible for JWT verification and public route RBAC.
  • ADMIN may manage all courses unless an organization filter is explicitly applied.
  • TEACHER may manage courses where instructorId or createdById equals the actor.
  • STUDENT may read course detail and record progress only with an active, unexpired enrollment and PUBLISHED course status.
  • PARENT is not part of the P8-005 course foundation.

Database:

  • services/course-service/migrations/000002_courses.sql creates courses, course_sections, course_lessons, course_materials, course_enrollments, course_lesson_progress, course_video_progress, and course_material_views.
  • Cross-service ids such as organization_id, subject_id, topic_id, instructor_id, created_by_id, uploaded_by_id, and student_id are stored as public ids; course-service does not query other service databases.
  • course_lessons.video_asset_id and material storage fields store document-service references only.
  • CourseLessonQuestion, CourseQuiz, StudentMastery, wallet purchase records, and canonical media metadata remain deferred.

Rollback for this native slice:

  • Keep /api/courses*, /api/student/courses*, and /api/public/catalog* routed to legacy.
  • Disable gateway callers for /v1/courses*, /v1/student/courses*, and /v1/public/courses*.
  • Keep question links, quizzes, report, mastery, recommendation, wallet purchase, and file streaming on legacy until their dedicated adapters land.
  • Drop course-service local course tables with the migration down step if local test data must be reset.

Gateway rehearsal:

deploy/gateway/routes.student-courses-read-native-example.json and deploy/gateway/routes.student-courses-read-native-localhost-example.json provide non-default route-table rehearsals for student course reads. They route only:

  • GET /api/student/courses
  • GET /api/student/courses/{courseId}

to course-service with gateway auth, STUDENT role enforcement, and organization header injection. Recommendation, purchase, lesson progress, video progress, material view, teacher/admin course management, public catalog, broad student-course/course/public routes, and fallback stay legacy-proxied until the missing adapters are explicit.

Run make test-student-course-routes before any live or browser rehearsal.

Student-course progress gateway rehearsal:

deploy/gateway/routes.student-course-progress-native-example.json and deploy/gateway/routes.student-course-progress-native-localhost-example.json provide non-default route-table rehearsals for student course progress writes. They route only:

  • POST /api/student/courses/{courseId}/lessons/{lessonId}/progress
  • POST /api/student/courses/{courseId}/lessons/{lessonId}/video-progress
  • POST /api/student/courses/{courseId}/materials/{materialId}/view

to course-service with gateway auth, STUDENT role enforcement, and organization header injection. Student course list/detail are covered by the separate read rehearsal and remain legacy in this progress-only table. Mastery, recommendation, purchase, teacher/admin course management, public catalog, broad student-course/course/public routes, and fallback stay legacy-proxied until the missing adapters are explicit.

Run make test-student-course-progress-routes before any live or browser rehearsal.

Non-goals for P8-005:

  • Public gateway adapter/cutover.
  • Wallet purchase and AZ Credit consumption.
  • Course lesson question links and quiz/exam contracts.
  • Mastery recalculation, recommendations, and full course reports.
  • File byte streaming and signed URL generation.
  • Cross-service validation against school-service, user-service, question-bank-service, exam-service, document-service, or wallet services.

Go-platform documentation is generated from repository Markdown.

Copyright 2026 HocTapAZ