FLAMES

Games for two, wherever you are.

Seven playful games. A little nostalgia. More reasons to talk.

Play the live demo ↗ · Explore the architecture · Contribute

---

FLAMES turns the familiar name game into a small collection of shared experiences: quick questions, playful predictions, date ideas, and conversations. Play on one device or connect through a room code when you're apart.

Inside the experience

Game	The idea
Classic FLAMES	Watch the name-matching calculation unfold, step by step.
Cute Name Generator	Discover a couple nickname derived from your names.
Your Song	Answer a few questions and find a song through vector similarity.
Would You Rather	Pick a side and discover where you agree.
Rapid Fire	Make quick choices before the timer runs out.
Expectation vs Reality	Compare your predictions with your partner's answers.
Sweet Truth or Dare	Take turns with a curated collection of prompts.

Beyond the games: an animated sky wheel, a date-idea spinner, downloadable result cards, real-time room chat, sound effects, and reduced-motion support. Ladki Ki Dost adds a streamed AI conversation companion for two people sharing a device.

Engineering highlights

• One reusable game shell: setup, turn-taking, progress, results, and sharing are shared across games.
• Deterministic game logic: the FLAMES engine returns a full step log, keeping the animation aligned with the calculation.
• Curated content first: a shuffle bag tracks seen IDs and recycles the content bank when needed.
• Real-time play: Firebase Anonymous Auth and Firestore synchronize room state, presence, and chat.
• Client-side share cards: Canvas renders cards locally without sending names to a rendering server.
• Streamed conversations: a server-side Groq integration, structured intake, request validation, and deterministic safety screening support the conversation flow.

flowchart LR
    A[Next.js interface] --> B[Shared game shell]
    B --> C[Pure game engines and content banks]
    B <--> D[Firebase Auth and Firestore]
    B --> E[Canvas share cards]
    A --> F[Talk route: validation and safety screening]
    F --> G[Groq streaming API]

Loading

Run locally

Use Node.js 24 and npm. The lockfile pins the dependency tree.

git clone https://github.com/Omshri07/flames.git
cd flames
npm ci

Copy .env.local.example to .env.local (Copy-Item .env.local.example .env.local in PowerShell, or cp .env.local.example .env.local on macOS/Linux), then enter your own Firebase web app configuration.

1. Create a Firebase project and register a web app.
2. Enable Anonymous sign-in in Firebase Authentication and create a Firestore database.
3. Review and deploy firestore.rules to that project. Configure its authorized domains for your local or hosted app.
4. Set the four required Firebase variables below. Add a Groq key to enable the conversation companion.
5. Run npm run dev and open localhost:3000.

Variable	Purpose
NEXT_PUBLIC_FIREBASE_API_KEY	Required Firebase web configuration
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN	Required Firebase authentication domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID	Required Firebase project ID
NEXT_PUBLIC_FIREBASE_APP_ID	Required Firebase web app ID
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET	Optional Firebase storage configuration
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID	Optional Firebase sender configuration
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID	Optional analytics configuration
GROQ_API_KEY	Server-only key for Ladki Ki Dost

Firebase configuration is needed by the client module even when testing same-device games. Never put the Groq key in a NEXT_PUBLIC_ variable or commit .env.local.

Development

Command	Purpose
npm run dev	Start the development server
npm test	Run the Vitest suite
npm run lint	Run ESLint with zero warnings allowed
npm run build	Compile the production app and check TypeScript
npm start	Serve the production build

Tests cover game engines, content selection, sound gating, analytics, and the conversation intake, route, and safety behavior. GitHub Actions runs tests, lint, and a production build with dummy Firebase configuration; it does not exercise live external services.

Project map

app/                 Pages, layouts, and server routes
components/          Game UI, shared shell, and animated chrome
lib/games/           Game registry and shared types
lib/flames/          Pure FLAMES calculation and step log
lib/content/         Curated prompt banks
lib/firebase/        Authentication, rooms, and analytics
lib/talk/            Conversation intake and safety logic
lib/ai/              Server-side model integration and persona
lib/card/            Local share-card rendering
docs/                Architecture documentation and project assets

Privacy and current limits

Same-device game state is held in memory; content history stores seen IDs. Far-away play sends room and chat data to Firestore. Conversation messages are sent to the configured AI provider, while the app keeps the conversation transcript in React state. Optional Firebase Analytics has separate data handling. See the app's About page and service notes.

Far-away Ladki Ki Dost, durable distributed rate limiting, and automatic cleanup of idle Firestore rooms remain follow-up work. The companion is an AI conversation feature, not professional care. Provider availability and usage limits apply.

Explore further

• Documentation index
• Architecture and tradeoffs
• Contribution guide

License: no open-source license has been granted in this repository.