How techaccecho/puzzle-apps works
Puzzle Apps is a Fastify-backed ARG puzzle site. Players enter through the served game pages, request a user-specific Wordsearch, validate selections to unlock a short URL, then use the ASCII-art terminal to submit a passcode and reach the gated Haven destination. Admins manage dictionary content, redirect mappings, and puzzle/URL visibility. The sampled services show Convex persistence and ASCII-art calls to the external state service; other route-to-service details are documented in the README but not all handler bodies were sampled.
Main entry points: api.ts API routes · index.ts Fastify server · WordSearchService.ts Wordsearch engine · ConvexService.ts Convex adapter
Components 19
Web entry and UI
- Fastify server
src/index.ts - Game pages
src/fe - API routes
src/routes/api.ts - Admin dashboard
src/fe/admin/admin.html - Wordsearch UI
src/fe/word-search/wordsearch.html - ASCII terminal UI
src/fe/ascii-art/asciiart.html - Haven page
src/fe/haven/unlisted_lagoon.html
Puzzle services
- Wordsearch engine
src/services/word-search/WordSearchService.ts - Dictionary service
src/services/word-search/DictionaryService.ts - ASCII passcode
src/services/ascii-art/AsciiArtService.ts - Short URL service
src/services/url-shortner/UrlShortenerService.ts
Admin and configuration
- Admin service
src/services/admin-portal/adminService.ts - Runtime configuration
src/config/env.ts
Persistence and state
- Convex adapter
src/services/convex/ConvexService.ts - Convex database
- ARG state service
- Service response helpers
src/services/BaseApiService.ts
Other components
- Player
- Administrator
Connections 31
- Player → Fastify server: opens pages
README.md - Administrator → Fastify server: opens dashboard
README.md - Fastify server → Game pages: serves
src/index.ts - Fastify server → API routes: registers routes
src/index.ts - Player → API routes: requests puzzles
README.md - Administrator → API routes: manages content
README.md - Game pages → API routes: calls endpoints
- API routes → Wordsearch engine: dispatches
src/routes/api.ts - API routes → ASCII passcode: dispatches
src/routes/api.ts - API routes → Short URL service: dispatches
src/routes/api.ts - API routes → Admin service: dispatches
src/routes/api.ts - Wordsearch engine → Dictionary service: selects words
src/services/word-search/WordSearchService.ts - Wordsearch engine → Short URL service: creates code
src/services/word-search/WordSearchService.ts - ASCII passcode → Wordsearch engine: resets puzzle
src/services/ascii-art/AsciiArtService.ts - Wordsearch engine → ASCII passcode: notifies completion
src/services/word-search/WordSearchService.ts - Wordsearch engine → Convex adapter: reads and writes
src/services/word-search/WordSearchService.ts - Dictionary service → Convex adapter: reads and writes
src/services/word-search/DictionaryService.ts - Short URL service → Convex adapter: reads and writes
src/services/url-shortner/UrlShortenerService.ts - Admin service → Convex adapter: reads and writes
src/services/admin-portal/adminService.ts - Convex adapter → Convex database: queries and mutates
src/services/convex/ConvexService.ts - ASCII passcode → ARG state service: checks and completes steps
src/services/ascii-art/AsciiArtService.ts - Admin dashboard → API routes: uses admin API
- Wordsearch UI → API routes: uses puzzle API
- ASCII terminal UI → API routes: uses puzzle API
- Fastify server → Admin dashboard: serves dashboard
src/index.ts - Fastify server → Wordsearch UI: serves page
src/index.ts - Fastify server → ASCII terminal UI: serves page
src/index.ts - Fastify server → Haven page: serves gated page
src/index.ts - Convex adapter → Service response helpers: extends
src/services/convex/ConvexService.ts - Admin service → Dictionary service: delegates edits
src/services/admin-portal/adminService.ts - ASCII passcode → Runtime configuration: uses settings
src/services/ascii-art/AsciiArtService.ts