The recommendation engine functions as an autonomous subsystem, isolated from the server's web framework to ensure architectural independence and algorithm reusability. The engine implements content-based filtering, scoring activities based on their metadata attributes rather than user interaction patterns. This approach provides an explainable alternative to opaque collaborative filtering methods.
Note: For detailed scoring formulas, design rationale, and pedagogical principles, see the thesis (Section 5.3.3, Architecture chapter).
| Category | Impact | Description |
|---|---|---|
| Age Appropriateness | 4 | Tolerance-based matching with linear decay for activities outside target range |
| Bloom's Alignment | 5 | Hierarchical matching recognising cognitive progression across six levels |
| Topic Relevance | 4 | Proportional coverage of requested computational thinking topics |
| Duration Fit | 3 | Symmetric penalty model for deviations from target duration |
| Series Cohesion | 3 | For lesson plans: Topic overlap and Bloom progression between consecutive activities |
Aggregation: total_score = Σ(category_score × impact) / Σ(impact)
Activities must pass filters for age (within ±2 years), format, duration constraints, and resource requirements before scoring. This eliminates incompatible candidates early.
- Stage 1: Score all candidates by age, Bloom alignment, and topic; select top 25 by preliminary score
- Stage 2: Generate activity combinations from top 25 only; insert breaks; re-score with duration
This limits combinatorial complexity from O(n!) to O(25^k), achieving sub-three-second response times.
Generates 2-5 activity sequences with:
- Combinatorial limit: Top 25 activities only
- Pedagogical coherence via series cohesion scoring
- Bloom progression enforcement (non-decreasing)
- Topic overlap between consecutive activities
Automated break calculation using rule-based logic:
| Break Type | Duration | Trigger |
|---|---|---|
| Cleanup | Variable | Based on activity metadata |
| Mental Rest | 10 min | After high mental load activities |
| Physical Rest | 5 min | After high physical energy activities |
| Format Transition | 5 min | When activity format changes |
Note: Breaks never added after the final activity in a lesson plan.
The engine is implemented in Java within the activitymanagement package:
| Class | Responsibility |
|---|---|
RecommendationService |
Main orchestration - translates API criteria, invokes hard filters and scoring |
ScoringEngineService |
Individual category scoring functions |
activitymanagement/entity/enums/ |
Enum types for format, Bloom level, topics, resources |
Source paths under server/src/main/java/com/learnhub/activitymanagement/service/.
- Input:
RecommendationRequestDTO (targetAge, format, bloomLevels, targetDuration, preferredTopics, priorityCategories) - Output: Ranked list of
RecommendationResponsewith per-category score breakdowns
- Candidate Limit: Top 25 activities before expensive sequence generation
- Hard Filtering: Reduces initial candidate pool before scoring
- Two-Stage Pipeline: Defers expensive duration/break logic to Stage 2
- Integer Arithmetic: Uses [0-100] integer scales for efficiency
For detailed performance benchmarks and analysis, see the thesis (Chapter 6, Validation).