An interactive detective game for Miro that teaches SQL through mystery solving. Players write SQL queries against an in-browser SQLite database to uncover clues, reveal suspects, and close the case.

• In-browser SQL engine powered by sql.js (SQLite compiled to WebAssembly)
• Interactive Miro board with cinematic reveal sequences — camera pans, evidence webs, red string connectors, and suspect card flips
• AI-generated mysteries using Google Gemini for infinite replayability
• AI detective partner that provides contextual, escalating hints
• AI image generation using Gemini Imagen to visualize clues and evidence
• Text-to-speech narration via ElevenLabs API
• Anti-tampering system that detects destructive SQL and tracks integrity strikes
• Multiple difficulty levels from beginner JOINs to advanced CTEs and window functions
• Game state persistence via localStorage for resuming investigations
• Fallback mysteries so the game works even without an API key

• Node.js v16+
• A Miro developer account with a registered app
• A Google Gemini API key (optional — fallback mysteries are built-in)

git clone <your-repo-url>
cd sql-side-quest
npm install

cp node_modules/sql.js/dist/sql-wasm.wasm public/

On Windows (PowerShell):

Copy-Item node_modules/sql.js/dist/sql-wasm.wasm public/

cp .env.example .env

Edit .env and fill in your values:

1. Go to the Miro Developer Portal
2. Set App URL to http://localhost:3000
3. Set SDK URI to /app.html
4. Enable boards:read and boards:write permissions

# Frontend only (uses built-in fallback mysteries)
npm run dev

# Frontend + AI API server (enables Gemini mystery generation and hints)
npm run dev:full

Open any Miro board and launch the SQL Side Quest app from the toolbar.

src/
  app.tsx              # Root React component
  components/          # React UI components
  engine/              # SQL engine, game state, validation, tamper detection
  board/               # Miro board layout, choreography, item helpers
  ai/                  # LLM integration (mystery generation, hints, prompts)
  data/                # Sample and fallback mystery data
  types/               # TypeScript type definitions
  utils/               # Helpers (sleep, storage, imageLoader)
api/
  generate.ts          # Mystery generation endpoint
  hint.ts              # Hint generation endpoint
  dev-server.ts        # Local dev API server
public/
  image/               # Images loaded onto the board
  gif/                 # Animated GIFs for ambient effects

MIT