Get Hedhog updates in your inbox

New releases, fresh recipes, and breaking changes — no spam.

LMS Submodule

achievements

Badges and rewards for learning milestones (course/path completion, exam approval, attendance, engagement), each awarding Bitcodes — plus the underlying AI-driven lesson XP system (areas/skills/learning-types taxonomy, time-coded video XP segments, and per-student XP ledgers) that feeds the platform's broader gamification layer.

Source path: libraries/lms/src/achievement (+ lesson-xp-map, xp-catalog, student-xp)

Module file: achievement.module.ts, lesson-xp-map.module.ts, xp-catalog.module.ts, student-xp.module.ts

Introduction

Achievements are the player-facing reward layer: a badge with a `type` (course_completion, learning_path_completion, exam_approval, attendance, engagement, or custom), an icon and main image, and a `bitCodesValue` that determines how many Bitcodes (see the Bitcode Wallets submodule) a student receives when it is granted. `canReceiveMultipleTimes` distinguishes one-off milestones (e.g. "completed your first course") from repeatable ones (e.g. "attended 10 sessions"). The controller itself is a thin CRUD surface; the actual granting logic (which event triggers which achievement) lives outside this submodule's files and was not traced as part of this inventory.

The Lesson XP system, while owned by three separate, dedicated source folders (`lesson-xp-map`, `xp-catalog`, `student-xp`) rather than the achievement folder itself, is documented here because it is the platform's other major gamification mechanism and has no closer-fitting slug among the existing thirteen — it shares the same "reward learners for engaging with content" purpose as Achievements, just at a finer grain. The taxonomy (`xp-catalog`) is a three-level structure: Areas (broad subject/competency categories), Skills (optionally nested under an Area), and Learning Types (a modality like video or quiz, carrying its own XP multiplier) — all bilingual (pt/en name and description fields). `lesson-xp-map` lets an AI pipeline (or an admin) segment a lesson's video timeline into time-coded ranges, each carrying an XP value, a difficulty rating, a should-grant-XP flag, and optional weighted links into the Areas/Skills/Learning-Types taxonomy; maps go through an explicit admin review workflow (pending → processing → ready/needs_review → approved/rejected) before their XP becomes live. `student-xp` is the resulting ledger: a raw event log of every XP grant, pre-aggregated balance views by area/skill/learning-type, a self-service "my balance" lookup, and a `skill-card` endpoint that lets a student self-report a non-video XP-earning action (looked up by skill slug) outside the lesson-segment pipeline.

None of `lesson-xp-map`, `xp-catalog`, or `student-xp` currently expose any MCP tools — they are HTTP-only. All are fully wired into `LmsModule` and reachable via permissioned routes; they are not internal/unexposed despite living outside the Achievements source folder.

HTTP Endpoints

47 endpoints

Paginated achievement list.

Query: page, pageSize, search

Gets an achievement by ID.

Params: id (int)

Creates an achievement.

Body

Field	Type	Required	Notes
name	string	yes	Max 255 chars
type	'course_completion' \| 'learning_path_completion' \| 'exam_approval' \| 'attendance' \| 'engagement' \| 'custom'	yes	—
bitCodesValue	number	yes	Min 0
canReceiveMultipleTimes	boolean	yes	—
description	string \| null	no	—
iconFileId	number	no	Min 1
mainImageFileId	number	no	Min 1

Updates achievement fields.

Params: id (int)

Deletes an achievement; 204 No Content.

Params: id (int)

Paginated list of XP areas.

Query: page, pageSize, search, status

All XP areas, unpaginated.

Aggregate stats for XP areas.

Gets a single XP area.

Params: id (int)

Creates an XP area.

Body

Field	Type	Required	Notes
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
iconSlug	string	no	Max 100 chars
color	string	no	Max 9 chars
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Updates an XP area (all fields optional).

Params: id (int)

Deletes an XP area; 204 No Content.

Params: id (int)

Paginated list of XP skills, optionally filtered by area.

Query: page, pageSize, search, status, areaId

All skills, optionally filtered by area, unpaginated.

Query: areaId?

Aggregate stats for XP skills.

Gets a single XP skill.

Params: id (int)

Creates an XP skill, optionally nested under an area.

Body

Field	Type	Required	Notes
xpAreaId	number	no	Min 1
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Updates a skill (all fields optional).

Params: id (int)

Deletes a skill; 204 No Content.

Params: id (int)

Paginated list of XP learning types.

Query: page, pageSize, search, status

All learning types, unpaginated.

Gets a single learning type.

Params: id (int)

Creates a learning type (modality with its own XP multiplier).

Body

Field	Type	Required	Notes
slug	string	yes	Max 100 chars
namePt	string	yes	—
nameEn	string	yes	—
descriptionPt	string	no	—
descriptionEn	string	no	—
multiplier	number	no	Min 0
sortOrder	number	no	—
status	'active' \| 'inactive'	no	—

Updates a learning type (all fields optional).

Params: id (int)

Deletes a learning type; 204 No Content.

Params: id (int)

Paginated list of lesson XP maps.

Query: page, pageSize, search, status, courseLessonId

Creates a new lesson XP map for a course lesson.

Body

Field	Type	Required	Notes
courseLessonId	number	yes	Min 1
version	number	no	Min 1
aiModelVersion	string	no	Max 100 chars

Gets the XP map for a lesson, or null if none exists.

Params: lessonId (int)

Per-lesson overview for a course: total XP, map status, segment count.

Params: courseId (int)

Triggers AI-based recalculation of XP segments/values for the lesson.

Params: lessonId (int)

Gets a single lesson XP map.

Params: id (int)

Updates a map's status/review fields.

Params: id (int)

Body

Field	Type	Required	Notes
status	'pending' \| 'processing' \| 'ready' \| 'needs_review' \| 'approved' \| 'rejected'	no	—
reviewNotes	string	no	—
aiModelVersion	string	no	Max 100 chars
processingError	string	no	—
totalXp	number	no	Min 0

Deletes a lesson XP map; 204 No Content.

Params: id (int)

Approves the map, recording reviewer and timestamp.

Params: id (int)

Rejects the map, recording reviewer, timestamp, and notes.

Params: id (int)

Body

Field	Type	Required	Notes
reviewNotes	string	no	—

Paginated list of XP segments for a map.

Params: id (int, map id)
Query: page, pageSize

Creates a time-coded XP segment with optional weighted links into the Areas/Skills/Learning-Types taxonomy.

Params: id (int, map id)

Body

Field	Type	Required	Notes
startSeconds	number	yes	Min 0
endSeconds	number	yes	Min 0
xpValue	number	yes	Min 0
difficulty	'easy' \| 'medium' \| 'hard' \| 'expert'	yes	—
shouldGrantXp	boolean	yes	—
aiSummary	string	no	—
aiConfidence	number	no	0 to 1
sortOrder	number	no	—
areas	{ xpAreaId, weightPercent }[]	no	weightPercent 0.01–100
skills	{ xpSkillId, weightPercent }[]	no	—
learningTypes	{ xpLearningTypeId, weightPercent }[]	no	—

Gets a single XP segment.

Params: id (int)

Updates a segment (same shape as create, all optional).

Params: id (int)

Deletes a segment; 204 No Content.

Params: id (int)

Paginated raw ledger of XP-grant events.

Query: page, pageSize, personId, courseLessonId, source

Paginated per-person XP balances aggregated by area.

Query: page, pageSize, personId, areaId

Paginated per-person XP balances aggregated by skill.

Query: page, pageSize, personId, skillId

Paginated per-person XP balances aggregated by learning type.

Query: page, pageSize, personId, learningTypeId

Full balance summary for one person across areas/skills/learning-types.

Params: personId (int)

Self-service: the caller's own XP balance summary, resolved via their person_user link.

Self-service XP grant by skill slug, outside the lesson-segment pipeline.

Body

Field	Type	Required	Notes
skillCardSlug	string	yes	—
xpEarned	number	yes	Min 1

MCP Tools

Named tools callable by AI models via the Model Context Protocol (MCP).

lms.achievements.list
Lists LMS achievements with optional pagination and search
lms.achievements.get
Returns a single LMS achievement by ID
lms.achievements.create
Creates a new LMS achievement
lms.achievements.update
Updates an existing LMS achievement
lms.achievements.delete
Deletes an LMS achievement by ID