Game of Choice

Overview

This project is an AI-powered life simulator that uses Google Gemini APIs to simulate real-world decision-making and progression. Users interact with an AI system that acts as a dynamic life guide, adapting outcomes based on choices and providing an evolving experience.

The simulator tracks important aspects like wealth, health, happiness, intelligence, and relationships, and dynamically changes these values depending on user decisions.

Tech Stack

Frontend Framework

• Next.js 15.2.6 - React framework with App Router architecture
• React 19 - UI library with latest features
• TypeScript 5 - Type-safe development

UI & Styling

• Tailwind CSS 4.1.9 - Utility-first CSS framework
• Radix UI - Accessible component primitives (Dialog, Dropdown, Toast, etc.)
• shadcn/ui - Pre-built component library built on Radix UI
• Geist Font - Modern typography (Sans & Mono variants)
• next-themes - Dark/light mode theme provider
• Lucide React - Icon library

Authentication & User Management

• Clerk - Complete authentication solution with user management
  • Handles sign-in, sign-up, and user sessions
  • Integrated with middleware for route protection
  • User profiles synced with database

Database & Backend

• Supabase - PostgreSQL database with real-time capabilities
  • Row Level Security (RLS) for data access control
  • Server-side functions for rate limiting and game logic
  • JSONB columns for flexible game state storage
  • Materialized views for optimized leaderboard queries

AI Integration

• Google Gemini API (gemini-3-flash-preview) - AI-powered content generation
  • Multi-key rotation system for handling rate limits
  • Automatic retry logic with exponential backoff
  • Safety filters for content moderation
  • Custom prompt engineering for game events and evaluations

Analytics & Monitoring

• Vercel Analytics - Performance and user analytics

Form Handling & Validation

• React Hook Form - Form state management
• Zod - Schema validation
• @hookform/resolvers - Zod integration for React Hook Form

Additional Libraries

• date-fns - Date manipulation utilities
• recharts - Data visualization for game statistics
• sonner - Toast notifications
• cmdk - Command palette component

Architecture

Application Structure

The application follows Next.js App Router architecture with a clear separation of concerns:

Server Actions Pattern

• All backend logic is implemented as Server Actions (marked with "use server")
• Server actions handle:
  • Game state management
  • AI API calls (Gemini integration)
  • Database operations (Supabase)
  • Rate limiting checks
  • Game session persistence

Authentication Flow

1. Clerk handles user authentication at the edge
2. Middleware (middleware.ts) protects game routes (/game/play, /game/complete)
3. User profiles are automatically created/updated in Supabase on first login
4. Clerk user IDs are used as the primary identifier across the system

Database Schema

Core Tables:

• profiles - User profiles linked to Clerk user IDs
• game_sessions - Completed game sessions with full state and statistics
• user_rate_limits - 24-hour cooldown tracking per user
• shareable_links - Public shareable links for game results

Database Functions:

• can_user_play() - Checks if user can start a new game (24-hour cooldown)
• update_rate_limit_after_game() - Updates rate limit after game completion
• refresh_leaderboard() - Refreshes materialized leaderboard view

Security:

• Row Level Security (RLS) enabled on all tables
• Policies allow public read access for leaderboard data
• Application-level validation for write operations

AI Integration Architecture

Multi-Key Rotation System:

• Supports up to 5 Gemini API keys for load distribution
• Automatic key rotation on rate limit (429) errors
• Retry logic with exponential backoff
• Fallback to static events if all API calls fail

AI Functions:

• generateGeminiEventAction() - Generates dynamic life scenarios based on game state
• evaluateCustomChoiceAction() - Evaluates user-created choices
• evaluateLifeEndingAction() - Evaluates completed life journeys
• evaluateCustomEndingAction() - Creates personalized endings from user input

Safety & Content Moderation:

• Built-in Gemini safety settings (harassment, hate speech, explicit content, dangerous content)
• Client-side content validation before API calls
• Graceful error handling for blocked content

Game State Management

Game State Structure:

• Tracks: age, health, wealth, happiness, intelligence, relationships
• Life stages: child, teen, adult, senior
• Choice history with full context
• Thought path selection (Ambitious, Hedonist, Stoic, Altruist, Scholar, Artist, Mindful)
• Dynamic event generation based on previous choices

State Persistence:

• Game sessions saved to database on completion
• Full game state stored as JSONB for flexibility
• Shareable links generated for completed games
• Leaderboard calculated from materialized view

Rate Limiting System

24-Hour Cooldown:

• Users can play one game per 24-hour period
• Tracked by both Clerk user ID and email address
• Database function checks cooldown status
• Automatic daily reset for game counters

Sharing & Social Features

Shareable Links:

• Unique tokens generated for each completed game
• Public/private link control
• View count tracking
• Links include full game session data with user profile

Leaderboard:

• Materialized view for performance
• Top 100 scores ranked by life score and final age
• Includes user profiles and game statistics

API Integration Patterns

Server Actions:

• All API calls happen server-side for security
• Environment variables for API keys (never exposed to client)
• Error handling with fallback mechanisms
• Type-safe interfaces for all data structures

Data Flow:

1. User interaction → Client component
2. Client calls Server Action
3. Server Action validates authentication
4. Server Action calls Gemini API or database
5. Response returned to client
6. Client updates UI state

Performance Optimizations

• Materialized views for leaderboard queries
• Database indexes on frequently queried columns
• Server-side rendering for initial page loads
• Client-side state management for game interactions
• Efficient JSONB storage for flexible game data

Core Idea

• The user is placed in a life simulation where every choice impacts their future.
• Wealth, health, happiness, intelligence, and relationships are tracked throughout the journey.
• AI (via Gemini API) generates realistic outcomes for decisions, making each user's life journey unique.
• Multiple Gemini API keys are pooled to handle scaling requests without exhausting limits.

Key Features

• Choice-based life simulation where each decision changes future paths.
• Dynamic stat tracking (Wealth, Health, Happiness, Intelligence, Relationships).
• AI-powered branching: Gemini generates new scenarios, so no two simulations are the same.
• Multi-key handling: Prevents API exhaustion by rotating multiple Gemini API keys.
• Rate limiting: 24-hour cooldown between games to manage API usage.
• Shareable results: Generate public links to share your life journey.
• Leaderboard: Compete with others based on life score and achievements.
• Custom endings: Create your own unique ending scenario.

Example Flow

1. The user starts the simulation with balanced stats and selects a thought path.
2. AI presents a life scenario (e.g., choosing between a safe job, risky startup, or freelancing).
3. The user selects an option or creates a custom choice.
4. Stats update dynamically — e.g., choosing a startup may increase wealth but reduce happiness/health due to stress.
5. AI generates the next scenario based on previous choices, continuing the story.
6. The journey continues until reaching a final age or life event.
7. AI evaluates the complete life journey and generates a personalized ending.
8. Results are saved and can be shared via a unique link.

Why It's Unique

• Unlike static games, this simulator is driven by real-time AI reasoning.
• The experience is infinite and evolving, as Gemini continuously creates new situations.
• It combines gamification + AI storytelling + life coaching simulation in one product.
• Collaborative storytelling where user choices influence AI-generated content.
• Personalized narratives that adapt to individual play styles and decisions.

---