GeoPuzzle

Gameplay runs over a persistent WebSocket connection. Rather than polling, the client drives the game by sending typed JSON commands and the server maintains the complete game state per connection.

• Commands: select, start, next, answer, exit
• Per-connection state — current stage, accumulated score, elapsed time
• Geographic scoring via the Haversine formula — 100 pts within radius, scaled 0–100 beyond
• Automatic scoreboard record written on game completion
• Two waypoint types: text puzzles and graphic puzzles (image upload)
• Tracks require both waypoints and tags before activation — enforced at Mongoose pre-save hook level

The server is built with Express.js and TypeScript (ESM), backed by MongoDB via Mongoose. A factory handler pattern provides generic CRUD operations shared across all models — controllers stay thin and consistent.

• Generic factory handlers — getAll, getOne, addOne, updateOne, deleteOne
• Advanced query class — filtering, full-text search, sorting, field limiting, pagination
• Global error handler with custom AppError class and catchAsync wrapper
• Swagger / OpenAPI documentation generated from JSDoc comments
• Security: Helmet, CORS, NoSQL-injection sanitisation, XSS cleaning, HPP prevention

Users authenticate with Google OAuth 2.0 via Passport.js. After the callback the server issues a signed JWT used for all protected requests. An ownership middleware ensures only the content creator can edit or delete their resources.

• Google OAuth 2.0 login and redirect flow
• JWT generation and validation on every protected route
• Ownership middleware — creator-only mutations
• User profiles linked to Google accounts by provider ID