docs: add CLAUDE.md for AI session context

2026-05-30 23:58:49 +00:00
parent 222e4e45ce
commit 7ab8cde0ad
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# MorseQuest — CLAUDE.md
+
+> AI context file for Claude Code sessions.
+
+## Project Identity
+
+**MorseQuest** is an adventure-based Morse code learning game. Players progress through 6 levels with personalized mnemonics, multi-modal audio-visual learning, and achievements. Targets amateur radio enthusiasts, Scout programs, and STEM education.
+
+- **Production**: https://morsequest.gamercomp.com (port 3004 on GamerComp VM)
+- **Repository**: https://git.keylinkit.net/allen/morsequest
+- **Game Platform**: Follows `/home/node/workspace/games/GAME_REFERENCE.md` patterns
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Frontend | React 18.2, TypeScript, Vite 5.1 |
+| Backend | Node.js HTTP server (CommonJS, no framework) |
+| Database | better-sqlite3 (WAL mode, closure pattern) |
+| Auth | Magic link email + guest login (nodemailer) |
+| PWA | Service worker, manifest.json, install prompt |
+| Testing | Vitest (client), node:test (server) |
+
+## Project Structure
+
+```
+morsequest/
+├── client/           # React frontend (Vite root: 'client')
+│   ├── src/          # Components, hooks, pages, lib
+│   └── public/       # sw.js, manifest.json, icon.svg
+├── server/
+│   ├── server.js     # HTTP routing, static serving
+│   ├── db.js         # All DB queries as closures inside initDb()
+│   ├── mailer.js     # Magic link emails
+│   └── tests/        # db.test.js, auth.test.js, progress.test.js, admin.test.js
+├── data/             # .db files (gitignored)
+├── Dockerfile        # Multi-stage, node:20-alpine, port 8080
+└── docker-compose.yml
+```
+
+## Development
+
+```bash
+npm install
+npm run dev          # Starts both client (Vite) and server (concurrently)
+```
+
+## Testing
+
+```bash
+# Server tests (node:test with real HTTP, :memory: DB)
+node --test server/tests/db.test.js server/tests/auth.test.js server/tests/progress.test.js server/tests/admin.test.js
+
+# Client tests (vitest)
+npx vitest run
+```
+
+## Deployment
+
+Docker on GamerComp VM (port 3004 → 8080 internal):
+```bash
+# Build and deploy
+npx vite build
+docker build -t morsequest .
+docker run -d --name morsequest -p 127.0.0.1:3004:8080 \
+  -e ADMIN_PASSWORD=<secret> \
+  -e SMTP_HOST=mail.keylinkit.net -e SMTP_PORT=2525 \
+  -e SMTP_USER=info@gamercomp.com -e SMTP_PASS='kitPLANE1!!' \
+  -e APP_URL=https://morsequest.gamercomp.com \
+  -v /home/ubuntu/game-arcade/games/morsequest/data:/app/data \
+  --restart unless-stopped morsequest
+```
+
+SSH: `ssh -i ~/.ssh/claude_gamercomp -p 2135 ubuntu@keylinkit.vpnplus.to`
+App dir: `/home/ubuntu/game-arcade/games/morsequest/`
+Nginx block: `/etc/nginx/sites-enabled/morsequest`