# 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`