Implement Puzzle Recommendation Engine

[Mkalbani]

Description

Build a recommendation module that suggests the next puzzle a player should attempt based on their history, performance, difficulty progression, and unsolved gaps. A good recommendation system keeps players in flow — not too easy, not too hard — and surfaces puzzles they are likely to enjoy based on their category and tag engagement patterns.

Acceptance Criteria

• A recommendations module is scaffolded at src/recommendations/
• GET /recommendations returns up to 5 personalised puzzle suggestions
• Recommendations exclude already-solved or currently active puzzles
• Logic factors in the player's most-played categories and most-successful difficulty tier
• A "challenge me" mode suggests one puzzle one tier above the player's current comfort zone
• Cold-start users (no history) receive curated beginner puzzles
• Recommendation results are cached per user for a configurable TTL
• Unit tests cover personalised selection, cold-start fallback, exclusion logic, and cache behaviour

[darius-daniel]

I'd like to work on this issue.

I plan to implement the recommendations module with personalized puzzle suggestions based on player history, category engagement, and difficulty progression, while handling cold-start users, exclusion rules, challenge mode, and per-user caching. I'll also include comprehensive unit tests covering the recommendation logic, fallback behavior, exclusions, and cache functionality to ensure the feature meets the acceptance criteria.

[grantfox-oss]

🦊 GrantFox — @darius-daniel has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #79)
2. Your PR will be reviewed by the MindFlowInteractive maintainers

Good luck! Track your progress on GrantFox.