Cosmic Quest

The brief was a wellness-challenge API: users, challenges and completions. On its own that is a to-do list with points. To make people come back, I turned it into a game: complete real-life challenges, earn points and resources, unlock planets, build and upgrade colonies on them, collect badges and climb a leaderboard.

That moves the difficulty into the backend. A single tap on “complete” now has to record the completion, pay out points and resources, and maybe award a badge, and none of those can happen twice or half-way. Spending is the same in reverse: unlocking a planet or upgrading a colony must never leave points gone and nothing to show for them.

• ChallengesAnyone signed in can create one; only its creator can edit or delete it. Completing one pays its points and one stardust, plus one ore when it is worth 20 points or more.
• PlanetsEach has an unlock cost in points. Challenges can be linked to planets as their missions.
• ColoniesOne per planet per player once it is unlocked. Building costs 5 stardust and 2 ore; each upgrade costs 3 and 2, up to level 5, and can rename it too.
• BadgesAwarded automatically at milestones: first completion, first planet, first colony, a level 2 colony, and creating a challenge.
• LeaderboardRanks players by everything they’ve earned, including points they’ve since spent on planets.

Eight tables. Three came from the brief (users, challenges, completions) and five are the game: planets, each player’s unlocked planets with the colony stored on the same row, the links between challenges and planets, badges and earned badges. Progress is spread across join tables instead of counters on the user, so every rule can be read straight off the data.

Unique keys do the first line of defence: one completion per user per challenge, one unlock and colony per user per planet, one of each badge per user. A duplicate request fails at the database even if the code above it gets the order wrong.

Express routes are only a list of middleware: every step validates, checks, writes or rewards, and passes on or answers with the right status. Unlocking a planet reads top to bottom as the rule it enforces.

router.post(
  "/:user_id/planets/:planet_id/unlock",
  jwtMiddleware.verifyToken,                         // 401
  checkOwnerMiddleware.checkOwnerMiddleware,         // 403 not you
  userPlanetController.checkUserExistMiddleware,     // 404
  planetController.checkPlanetExistMiddleware,       // 404
  userPlanetController.checkPlanetNotUnlockedMiddleware, // 409
  userPlanetController.checkSufficientPointsMiddleware,  // 400
  userPlanetController.unlockPlanetMiddleware,
  userPlanetController.deductPointsOrRollbackMiddleware,
  userPlanetController.returnUnlockStatsMiddleware,
  userPlanetController.awardPlanetBadgeMiddleware,
  userPlanetController.sendUnlockResponse
);

The API has 33 numbered endpoints across auth, users, challenges, completions, planets, colonies and badges. Registering hashes the password with bcrypt before insert; logging in accepts a username or an email; both end by issuing a JWT that the protected routes verify.

• Spend only if the balance covers it, in one statement

  Checking the balance in one query and deducting in the next leaves a gap two requests can race through. The deduction is a single UPDATE with the balance in its WHERE clause, so it either spends or changes nothing, and zero affected rows means “not enough”.

• Undo by hand when there is no transaction

  The course used plain callbacks without transactions, so each multi-step spend has a compensating step. An unlock inserts the row first (the unique key stops doubles), then deducts; if the deduction fails, it deletes the row. A colony deducts first, then builds; if the build fails, it refunds.

• Ownership comes from the token, not the URL

  Every route that changes a player’s data compares the user id in the verified token with the one in the path and answers 403 on a mismatch. Challenges and completions check their creator or owner the same way, so a valid login can’t edit someone else’s progress.

• Rank what was earned, not what is left

  Points are also the currency for planets. Ranking by the current balance would punish playing the game, so the leaderboard adds back the cost of every unlocked planet and ranks on total earned.

• Compensating steps aren’t transactions: if the server dies between a deduction and its refund, the player loses the resources.
• The rate limiter allows 5,000 requests per 15 minutes per IP, loose enough to be decoration.
• The JWT sits in browser storage and there is no refresh or revocation: a token is good until it expires.
• A seeded role column hints at admins, but there is no admin role or moderation of user-created challenges.
• Each challenge can only be completed once per player, which suits milestones better than daily habits.