# techaccecho/puzzle-apps architecture

> Architecture diagram of the GitHub repository techaccecho/puzzle-apps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/techaccecho/puzzle-apps
- Repository: https://github.com/techaccecho/puzzle-apps

## Overview

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: [`src/routes/api.ts`](https://github.com/techaccecho/puzzle-apps/blob/main/src/routes/api.ts) (API routes), [`src/index.ts`](https://github.com/techaccecho/puzzle-apps/blob/main/src/index.ts) (Fastify server), [`src/services/word-search/WordSearchService.ts`](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/word-search/WordSearchService.ts) (Wordsearch engine), [`src/services/convex/ConvexService.ts`](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/convex/ConvexService.ts) (Convex adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web entry and UI"]
  node_fastify["Fastify server<br/>[index.ts]"]
  node_pages["Game pages"]
  node_api["API routes<br/>[api.ts]"]
  node_adminui["Admin dashboard<br/>[admin.html]"]
  node_wordui["Wordsearch UI<br/>[wordsearch.html]"]
  node_asciiui["ASCII terminal UI<br/>[asciiart.html]"]
  node_haven["Haven page"]
end

subgraph group_puzzles["Puzzle services"]
  node_wordsearch["Wordsearch engine"]
  node_dictionary["Dictionary service"]
  node_ascii["ASCII passcode<br/>[AsciiArtService.ts]"]
  node_shortener["Short URL service"]
end

subgraph group_management["Admin and configuration"]
  node_adminservice["Admin service<br/>[adminService.ts]"]
  node_config["Runtime configuration<br/>[env.ts]"]
end

subgraph group_persistence["Persistence and state"]
  node_convexservice["Convex adapter<br/>[ConvexService.ts]"]
  node_convex[("Convex database")]
  node_state["ARG state service"]
  node_base["Service response helpers<br/>[BaseApiService.ts]"]
end

node_player(("Player"))
node_admin(("Administrator"))

node_player -->|"opens pages"| node_fastify
node_admin -->|"opens dashboard"| node_fastify
node_fastify -->|"serves"| node_pages
node_fastify -->|"registers routes"| node_api
node_player -->|"requests puzzles"| node_api
node_admin -->|"manages content"| node_api
node_pages -.->|"calls endpoints"| node_api
node_api -->|"dispatches"| node_wordsearch
node_api -->|"dispatches"| node_ascii
node_api -->|"dispatches"| node_shortener
node_api -->|"dispatches"| node_adminservice
node_wordsearch -->|"selects words"| node_dictionary
node_wordsearch -->|"creates code"| node_shortener
node_ascii -->|"resets puzzle"| node_wordsearch
node_wordsearch -->|"notifies completion"| node_ascii
node_wordsearch -->|"reads and writes"| node_convexservice
node_dictionary -->|"reads and writes"| node_convexservice
node_shortener -->|"reads and writes"| node_convexservice
node_adminservice -->|"reads and writes"| node_convexservice
node_convexservice -->|"queries and mutates"| node_convex
node_ascii -->|"checks and completes steps"| node_state
node_adminui -.->|"uses admin API"| node_api
node_wordui -.->|"uses puzzle API"| node_api
node_asciiui -.->|"uses puzzle API"| node_api
node_fastify -->|"serves dashboard"| node_adminui
node_fastify -->|"serves page"| node_wordui
node_fastify -->|"serves page"| node_asciiui
node_fastify -->|"serves gated page"| node_haven
node_convexservice -->|"extends"| node_base
node_adminservice -->|"delegates edits"| node_dictionary
node_ascii -->|"uses settings"| node_config

click node_fastify "https://github.com/techaccecho/puzzle-apps/blob/main/src/index.ts"
click node_pages "https://github.com/techaccecho/puzzle-apps/tree/main/src/fe"
click node_api "https://github.com/techaccecho/puzzle-apps/blob/main/src/routes/api.ts"
click node_wordsearch "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/word-search/WordSearchService.ts"
click node_dictionary "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/word-search/DictionaryService.ts"
click node_ascii "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/ascii-art/AsciiArtService.ts"
click node_shortener "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/url-shortner/UrlShortenerService.ts"
click node_adminservice "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/admin-portal/adminService.ts"
click node_config "https://github.com/techaccecho/puzzle-apps/blob/main/src/config/env.ts"
click node_convexservice "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/convex/ConvexService.ts"
click node_adminui "https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/admin/admin.html"
click node_wordui "https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/word-search/wordsearch.html"
click node_asciiui "https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/ascii-art/asciiart.html"
click node_haven "https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/haven/unlisted_lagoon.html"
click node_base "https://github.com/techaccecho/puzzle-apps/blob/main/src/services/BaseApiService.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fastify,node_pages,node_api,node_adminui,node_wordui,node_asciiui,node_haven toneBlue
class node_wordsearch,node_dictionary,node_ascii,node_shortener toneAmber
class node_adminservice,node_config toneMint
class node_convexservice,node_convex,node_state,node_base toneRose
class node_player,node_admin toneIndigo
```

## Components

### Web entry and UI

- [Fastify server](https://github.com/techaccecho/puzzle-apps/blob/main/src/index.ts): `src/index.ts`
- [Game pages](https://github.com/techaccecho/puzzle-apps/tree/main/src/fe): `src/fe`
- [API routes](https://github.com/techaccecho/puzzle-apps/blob/main/src/routes/api.ts): `src/routes/api.ts`
- [Admin dashboard](https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/admin/admin.html): `src/fe/admin/admin.html`
- [Wordsearch UI](https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/word-search/wordsearch.html): `src/fe/word-search/wordsearch.html`
- [ASCII terminal UI](https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/ascii-art/asciiart.html): `src/fe/ascii-art/asciiart.html`
- [Haven page](https://github.com/techaccecho/puzzle-apps/blob/main/src/fe/haven/unlisted_lagoon.html): `src/fe/haven/unlisted_lagoon.html`

### Puzzle services

- [Wordsearch engine](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/word-search/WordSearchService.ts): `src/services/word-search/WordSearchService.ts`
- [Dictionary service](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/word-search/DictionaryService.ts): `src/services/word-search/DictionaryService.ts`
- [ASCII passcode](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/ascii-art/AsciiArtService.ts): `src/services/ascii-art/AsciiArtService.ts`
- [Short URL service](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/url-shortner/UrlShortenerService.ts): `src/services/url-shortner/UrlShortenerService.ts`

### Admin and configuration

- [Admin service](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/admin-portal/adminService.ts): `src/services/admin-portal/adminService.ts`
- [Runtime configuration](https://github.com/techaccecho/puzzle-apps/blob/main/src/config/env.ts): `src/config/env.ts`

### Persistence and state

- [Convex adapter](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/convex/ConvexService.ts): `src/services/convex/ConvexService.ts`
- **Convex database**
- **ARG state service**
- [Service response helpers](https://github.com/techaccecho/puzzle-apps/blob/main/src/services/BaseApiService.ts): `src/services/BaseApiService.ts`

### Other components

- **Player**
- **Administrator**

## Connections

- Player → Fastify server: opens pages (evidence: `README.md`)
- Administrator → Fastify server: opens dashboard (evidence: `README.md`)
- Fastify server → Game pages: serves (evidence: `src/index.ts`)
- Fastify server → API routes: registers routes (evidence: `src/index.ts`)
- Player → API routes: requests puzzles (evidence: `README.md`)
- Administrator → API routes: manages content (evidence: `README.md`)
- Game pages → API routes: calls endpoints
- API routes → Wordsearch engine: dispatches (evidence: `src/routes/api.ts`)
- API routes → ASCII passcode: dispatches (evidence: `src/routes/api.ts`)
- API routes → Short URL service: dispatches (evidence: `src/routes/api.ts`)
- API routes → Admin service: dispatches (evidence: `src/routes/api.ts`)
- Wordsearch engine → Dictionary service: selects words (evidence: `src/services/word-search/WordSearchService.ts`)
- Wordsearch engine → Short URL service: creates code (evidence: `src/services/word-search/WordSearchService.ts`)
- ASCII passcode → Wordsearch engine: resets puzzle (evidence: `src/services/ascii-art/AsciiArtService.ts`)
- Wordsearch engine → ASCII passcode: notifies completion (evidence: `src/services/word-search/WordSearchService.ts`)
- Wordsearch engine → Convex adapter: reads and writes (evidence: `src/services/word-search/WordSearchService.ts`)
- Dictionary service → Convex adapter: reads and writes (evidence: `src/services/word-search/DictionaryService.ts`)
- Short URL service → Convex adapter: reads and writes (evidence: `src/services/url-shortner/UrlShortenerService.ts`)
- Admin service → Convex adapter: reads and writes (evidence: `src/services/admin-portal/adminService.ts`)
- Convex adapter → Convex database: queries and mutates (evidence: `src/services/convex/ConvexService.ts`)
- ASCII passcode → ARG state service: checks and completes steps (evidence: `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 (evidence: `src/index.ts`)
- Fastify server → Wordsearch UI: serves page (evidence: `src/index.ts`)
- Fastify server → ASCII terminal UI: serves page (evidence: `src/index.ts`)
- Fastify server → Haven page: serves gated page (evidence: `src/index.ts`)
- Convex adapter → Service response helpers: extends (evidence: `src/services/convex/ConvexService.ts`)
- Admin service → Dictionary service: delegates edits (evidence: `src/services/admin-portal/adminService.ts`)
- ASCII passcode → Runtime configuration: uses settings (evidence: `src/services/ascii-art/AsciiArtService.ts`)
