AI Playground - Creative Adventure

AI Playground is now organized as a product-style client-server app instead of a frontend-only AI demo.

Project Structure

• Frontend app: / (Vite + React)
• Backend API: /server (Node.js + Express + MongoDB)
• Architecture notes: /docs/ARCHITECTURE.md

Frontend Setup

1. Install dependencies:

   npm install

2. Create env:

   cp .env-example .env

   Set VITE_GOOGLE_CLIENT_ID (Google Cloud OAuth Web client ID — same value as server GOOGLE_CLIENT_ID). VITE_API_BASE_URL can stay empty for local dev (Vite proxies /api to the backend).
3. Run frontend:

   npm run dev

Frontend runs at http://localhost:5173.

Backend Setup

1. Install backend dependencies:

   npm --prefix server install

2. Create backend env:

   cp server/.env-example server/.env

   Set GOOGLE_CLIENT_ID (same as frontend), JWT_SECRET, MONGODB_URI, and optionally GEMINI_API_KEY.
3. Run backend:

   npm run server:dev

Backend runs at http://localhost:8080 with health check at /health.

Product Modules

• Creative Quest: mission-based drawing + AI scoring + XP
• Artful Guesswork: free drawing + AI object guessing feedback
• Story Builder: drawing-driven chapter generation and progression
• Leaderboard API: top players by XP/level

Production-Friendly Practices Included

• Backend owns AI orchestration and progression scoring
• Missions are generated by AI with user profile context (age group, skill level, level)
• Zod payload validation on AI endpoints
• MongoDB persistence for users, drawings, and stories
• Server-side Google Sign-In + JWT auth (no Firebase client SDK on frontend)
• Security headers with Helmet
• Structured request logs with Morgan
• Frontend API layer (src/lib/api.js) with token forwarding
• Vite API proxy for local development

Available Scripts

• npm run dev - run frontend
• npm run build - frontend production build
• npm run preview - preview frontend build
• npm run server:dev - run backend in watch mode
• npm run server:start - run backend in standard mode

API Endpoints (v1)

• POST /api/v1/auth/google — exchange Google ID token for app JWT
• GET /api/v1/users/me — current user profile (auth required)
• GET /api/v1/gallery — art gallery from MongoDB drawings/stories
• POST /api/v1/drawings/:id/feedback — guesswork correct/incorrect feedback
• POST /api/v1/ai/creative-quest/submit
• POST /api/v1/ai/guesswork/submit
• POST /api/v1/ai/stories/chapter
• GET /api/v1/leaderboard

Deploy to Vercel (whole monorepo)

Yes — you can host frontend + backend in one Vercel project from this repo. The layout is a lightweight monorepo (/ = Vite client, /server = Express API).

How it works

Part	Vercel target
React app	Static build from dist/ (Vite)
Express API	Serverless function at api/index.mjs
Routes	/api/* and /health → API; everything else → SPA

Local dev is unchanged: npm run dev + npm run server:dev.

Deploy steps

1. Push the repo to GitHub and import it in Vercel.
2. Leave Root Directory as . (repo root).
3. Vercel reads vercel.json — install, build, and rewrites are already configured.
4. Add Environment Variables in the Vercel project (Production + Preview):

Variable	Required	Notes
MONGODB_URI	Yes	MongoDB Atlas connection string
MONGODB_DB_NAME	No	Default ai_playground
GOOGLE_CLIENT_ID	Yes	Same OAuth Web client ID as frontend
JWT_SECRET	Yes	Long random secret
GEMINI_API_KEY	No	Mock AI works without it
VITE_GOOGLE_CLIENT_ID	Yes	Same as GOOGLE_CLIENT_ID
VITE_API_BASE_URL	No	Leave empty for same-origin /api
CLIENT_ORIGIN	No	Auto-set from VERCEL_URL if omitted
NODE_ENV	No	Set production in Production

5. In Google Cloud Console, add your Vercel URL to OAuth Authorized JavaScript origins (e.g. https://your-app.vercel.app).
6. Deploy. Test https://your-app.vercel.app/health and sign-in.

Limits and caveats

• AI routes call Gemini and may take 10–30s. Hobby plan functions timeout at 10s; Pro allows up to 60s (maxDuration in vercel.json). Upgrade or move AI-heavy workloads to Railway/Render if you hit timeouts.
• MongoDB Atlas must allow Vercel IPs (use 0.0.0.0/0 or Atlas Serverless).
• socket.io is listed in server deps but not used — safe to ignore on Vercel.
• For a separate API-only Vercel project, point root to server/ and use only the api/ handler pattern (frontend would set VITE_API_BASE_URL).

CLI deploy

npm i -g vercel
vercel

Environment Notes

Backend (server/.env):

• MONGODB_URI — required
• GOOGLE_CLIENT_ID + JWT_SECRET — required for sign-in
• GEMINI_API_KEY — optional (mock AI responses work without it)

Frontend (.env in project root):

• VITE_GOOGLE_CLIENT_ID — same OAuth Web client ID as server
• VITE_API_BASE_URL — empty locally (Vite proxy); set to your API URL in production