What is Snappy Idioms Dot Com?

An interactive, language-learning experience. Snappy Idioms Dot Com uses imagination, context, and active practice to build fluency, not just memorisation.

🏀 Slam Dunk Idioms Child App Architecture

Secure standalone deployment for external developers

Architecture Overview

The Slam Dunk Idioms game will be spun off as a standalone child app that:

Runs independently on its own domain (e.g., play.snappyidioms.basketball)
Connects to the main app's Mothership API for data and authentication
External developers have zero access to the main SnappyIdioms.com codebase
Uses the same security model as your existing Scrabble game (JWT tokens, API keys, HMAC signing)

Security Model

🔐 What External Developers Get:

Game API Key - Public identifier (e.g., slam_dunk_01)

HMAC Secret Key - For signing requests (never sent over wire)

API Documentation - Endpoints, schemas, examples

Starter Template - React boilerplate with auth already wired

🚫 What They DON'T Get:

Direct database access

Main app source code

User passwords or sensitive data

Admin or service role access

Other games' API keys or data

Data Flow Architecture

┌─────────────────────────────────────────────────────────────┐
│  User's Browser                                             │
│  (play.snappyidioms.basketball)                            │
│                                                             │
│  1. User clicks "Play Slam Dunk Idioms"                   │
│  2. Child app redirects to SnappyIdioms.com/auth           │
│  3. User logs in (if needed)                               │
│  4. Main app generates JWT token                           │
│  5. Redirects back with ?auth=TOKEN                        │
│  6. Child app validates token via Mothership API           │
│  7. Game starts with authenticated user                    │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  Child App Server (External Developer Controls)            │
│  - React/Next.js frontend                                   │
│  - Game logic and UI                                        │
│  - API proxy to Mothership                                  │
│  - NO direct database access                                │
└─────────────────────────────────────────────────────────────┘
                           ↓
                    HTTPS + HMAC
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  Mothership API (SnappyIdioms.com - YOU control)          │
│                                                             │
│  Endpoints:                                                 │
│  • POST /api/game/verify-token                             │
│    → Validates JWT, returns user data                      │
│                                                             │
│  • GET /api/game/idioms                                    │
│    → Returns basketball idioms (filtered by game_id)       │
│                                                             │
│  • GET /api/game/user-progress                             │
│    → Returns user's pearls, badges, stats                  │
│                                                             │
│  • POST /api/game/award-pearls                             │
│    → Awards pearls (with validation + fraud checks)        │
│                                                             │
│  • POST /api/game/save-score                               │
│    → Saves game results to leaderboard                     │
│                                                             │
│  Security: HMAC signature validation on every request      │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│  Base44 Database (Main App - YOU control)                  │
│  - User accounts                                            │
│  - Idioms library                                           │
│  - Pearls of Wisdom                                         │
│  - Golden Eggs                                              │
│  - Leaderboard                                              │
│  - Achievement badges                                       │
└─────────────────────────────────────────────────────────────┘

Implementation Steps for You

Step 1: Register the Game in Your System

Create a new GameDeveloper entity record:

{
  "developer_name": "Basketball Team",
  "developer_email": "basketball@external.dev",
  "game_name": "Slam Dunk Idioms",
  "game_id": "slam_dunk_01",
  "secret_key": "GENERATE_RANDOM_SECRET_HERE",
  "base_pearl_rate": 5,
  "status": "active",
  "allowed_endpoints": [
    "verify-token",
    "get-idioms",
    "get-user-progress",
    "award-pearls",
    "save-score"
  ]
}

Step 2: Create Mothership API Endpoints

You already have this pattern from your Scrabble game! Reuse and adapt these functions:

✅ functions/generateGameToken - Generate JWT for auth
✅ functions/verifyGameToken - Validate JWT
✅ functions/gameAPI - Main API handler
✅ functions/awardPearlsAtomic - Award rewards

⚠️ Important: Filter idioms by category: "basketball" or create a new game_id field on the Idiom entity.

Step 3: Provide Developer Package

Give external developers:

📦 Starter template repository (React + TypeScript)
📖 API documentation (endpoints, request/response formats)
🔑 Game API credentials (game_id + secret_key)
💡 Example code for auth flow
🧪 Test environment URL

Step 4: Monitor & Control

You maintain full control via:

🎛️ Kill switch: Set status: "suspended" to block all API calls instantly
📊 Usage tracking: Monitor api_calls_count and last_api_call
🔍 Audit logs: Track all pearl awards and score submissions
⚙️ Rate limiting: Enforce request limits per game
🛡️ Fraud detection: Validate scores, detect cheating patterns

Developer Starter Template (What They Build With)

External developers get a clean React template with authentication pre-wired:

File: `src/config.ts`

export const config = {
  gameId: 'slam_dunk_01',
  secretKey: process.env.HMAC_SECRET_KEY!, // From environment
  mothershipUrl: 'https://snappyidioms.com/api/game',
  authRedirectUrl: 'https://snappyidioms.com/auth',
};

File: `src/lib/mothership.ts`

import crypto from 'crypto';
import { config } from '../config';

// Generate HMAC signature for request
function signRequest(payload: any): string {
  const message = JSON.stringify(payload);
  return crypto
    .createHmac('sha256', config.secretKey)
    .update(message)
    .digest('hex');
}

// Call Mothership API
export async function callMothership(
  endpoint: string,
  data: any
) {
  const payload = { ...data, game_id: config.gameId };
  const signature = signRequest(payload);
  
  const response = await fetch(
    `${config.mothershipUrl}/${endpoint}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Game-ID': config.gameId,
        'X-Signature': signature,
      },
      body: JSON.stringify(payload),
    }
  );
  
  if (!response.ok) {
    throw new Error('Mothership API error');
  }
  
  return response.json();
}

File: `src/hooks/useAuth.ts`

import { useState, useEffect } from 'react';
import { callMothership } from '../lib/mothership';
import { config } from '../config';

export function useAuth() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  
  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const token = params.get('auth');
    
    if (token) {
      // Validate token via Mothership
      callMothership('verify-token', { token })
        .then((data) => {
          setUser(data.user);
          localStorage.setItem('gameToken', token);
        })
        .catch(() => redirectToLogin())
        .finally(() => setLoading(false));
    } else {
      const savedToken = localStorage.getItem('gameToken');
      if (savedToken) {
        callMothership('verify-token', { token: savedToken })
          .then((data) => setUser(data.user))
          .catch(() => redirectToLogin())
          .finally(() => setLoading(false));
      } else {
        redirectToLogin();
      }
    }
  }, []);
  
  function redirectToLogin() {
    const returnUrl = window.location.href;
    window.location.href = 
      `${config.authRedirectUrl}?return=${encodeURIComponent(returnUrl)}`;
  }
  
  return { user, loading };
}

Usage in Game Component:

import { useAuth } from './hooks/useAuth';
import { callMothership } from './lib/mothership';

function SlamDunkGame() {
  const { user, loading } = useAuth();
  
  async function loadIdioms() {
    const data = await callMothership('get-idioms', {
      category: 'basketball',
      difficulty: 'rookie'
    });
    return data.idioms;
  }
  
  async function awardPearls(amount: number) {
    await callMothership('award-pearls', {
      user_email: user.email,
      amount,
      reason: 'Completed basketball round'
    });
  }
  
  if (loading) return <div>Loading...</div>;
  
  return <div>Game UI here...</div>;
}

Benefits of This Architecture

✅ For You (Main App Owner):

• Full control over data and users
• Can revoke access instantly
• Monitor all game activity
• No risk to main codebase
• Shared reward economy (pearls, badges)
• Reuse existing infrastructure

✅ For External Developers:

• Clean separation of concerns
• Can deploy anywhere (Vercel, Netlify, etc.)
• No database setup needed
• Authentication handled for them
• Focus only on game UI/UX
• Access to existing user base

📌 Note: This is the exact same architecture as your Scrabble game (Famous.ai integration). You already have all the backend infrastructure built — just register a new game_id and hand developers the starter template!