Gamification Service

Core microservice in the Muscledia ecosystem responsible for tracking user progress, awarding points, managing levels, and granting badges based on activity events.

---

Tech Stack

Layer	Technology
Language	Java 21
Framework	Spring Boot, Spring WebFlux (reactive)
Database	MongoDB
Messaging	Apache Kafka (Spring Kafka)
Build	Maven
Auth	JWT Bearer tokens

---

Architecture

Event-driven and loosely coupled. The service consumes Kafka events from other Muscledia services, processes them against gamification rules, and updates user state in MongoDB. It exposes REST APIs for the frontend to query achievements and leaderboards.

Events Consumed:

• WorkoutCompletedEvent — awards XP, checks badge eligibility, updates streaks
• PersonalRecordEvent — triggers special PR-related rewards

Events Published (planned):

• AchievementEarnedEvent — notifies downstream notification service

---

Data Model

Single primary collection: userGamificationProfiles

{
  "_id": "userId",
  "points": 1250,
  "level": 12,
  "streaks": {
    "dailyWorkout": { "current": 7, "lastUpdate": "2025-07-09T12:00:00Z" }
  },
  "earnedBadges": [
    { "badgeId": "ObjectId", "earnedAt": "2025-06-15T09:00:00Z" }
  ],
  "currentQuests": [
    { "questId": "ObjectId", "objectiveProgress": 5, "status": "in_progress" }
  ]
}

---

API Reference

Base URL: http://localhost:8083
Auth: Bearer JWT token required on all endpoints
Format: application/json

Badges — /api/badges

Method	Endpoint	Description
POST	/api/badges	Create badge
GET	/api/badges	List all badges
GET	/api/badges/user/{userId}	Get user's earned badges
POST	/api/badges/{badgeId}/award/{userId}	Award badge to user
POST	/api/badges/eligible	Get eligible badges for user
DELETE	/api/badges/{badgeId}	Delete badge

Quests — /api/quests

Method	Endpoint	Description
POST	/api/quests	Create quest
GET	/api/quests/user/{userId}/active	Get active quests
POST	/api/quests/{questId}/start/{userId}	Start quest
PUT	/api/quests/{questId}/progress	Update progress
POST	/api/quests/{questId}/complete/{userId}	Complete quest
GET	/api/quests/user/{userId}/progress	Get quest progress

Champions — /api/champions

Method	Endpoint	Description
POST	/api/champions	Create champion
GET	/api/champions	List all champions
POST	/api/champions/{championId}/award/{userId}	Award champion
POST	/api/champions/eligible	Get eligible champions
GET	/api/champions/statistics	Champion statistics

User Profiles — /api/users

Method	Endpoint	Description
GET	/api/users/{userId}/profile	Get gamification profile
PUT	/api/users/{userId}/points	Update points
PUT	/api/users/{userId}/streaks	Update streak
GET	/api/users/{userId}/achievements	Achievement summary
GET	/api/users/leaderboards/points	Points leaderboard
GET	/api/users/leaderboards/levels	Level leaderboard
GET	/api/users/analytics/platform-stats	Platform stats (Admin)

---

Running Locally

Prerequisites: Java 21, Docker, Maven

# Start dependencies
docker-compose up mongodb kafka zookeeper -d

# Run service
mvn spring-boot:run

Service endpoints:

• API: http://localhost:8083
• Swagger UI: http://localhost:8083/swagger-ui.html
• Health: http://localhost:8083/actuator/health

---

Known Limitations

• Automated tests for Kafka consumer pipeline not yet implemented — identified gap, planned via Testcontainers
• AchievementEarnedEvent publishing is a future consideration pending notification service implementation