A therapeutic AI-powered RPG adventure designed to help young adults process trauma through interactive storytelling and journaling.
Play the Game: Play NOW
Video Demo: View on YouTube
Luminari's Quest is a therapeutic, AI-powered interactive RPG adventure designed to help young adults process trauma from losing parents and experiencing homelessness during their teenage years. The game combines fantasy storytelling with evidence-based therapeutic techniques to create a safe space for healing and growth.
This project addresses the critical need for accessible mental health resources by transforming traditional therapy concepts into engaging, interactive experiences. Built for the World's Largest AI Hackathon, it demonstrates how AI can be used for therapeutic purposes while maintaining clinical effectiveness.
- Evidence-Based: Incorporates cognitive behavioral therapy (CBT) and narrative therapy principles
- Trauma-Informed: Designed specifically for young adults with complex trauma histories
- Safe Space: Non-judgmental environment for emotional exploration and growth
- Progressive: Adapts to user's emotional readiness and therapeutic progress
- Frontend: React 18.2+ with TypeScript 5.3+ and Vite 6.3+
- Styling: Tailwind CSS 3.4+ with Shadcn/UI component library
- State Management: Zustand 5.0+ with persistence and hydration safety
- Routing: React Router 6.22+ with protected routes and lazy loading
- Animations: Framer Motion 12.18+ for therapeutic UX transitions
- Backend: Supabase (PostgreSQL with real-time capabilities)
- Authentication: Supabase Auth with email/password and social providers
- Database: PostgreSQL with Row Level Security (RLS) policies
- Real-time: Supabase real-time subscriptions for live updates
- Narrative AI: OpenAI GPT-4 for dynamic storytelling (planned)
- Image Generation: Leonardo.AI for scene illustrations (planned)
- Voice Synthesis: ElevenLabs for therapeutic narration (planned)
- Audio: React H5 Audio Player for background music and sound effects
- Build Tool: Vite with TypeScript compilation and hot reload
- Testing: Vitest 3.2+ with React Testing Library and Jest-axe
- Linting: ESLint 8.56+ with TypeScript and React plugins
- Formatting: Prettier 3.2+ with Tailwind plugin
- Deployment: Netlify with automatic builds and environment management
- Type Safety: Strict TypeScript configuration with zero compilation errors
- Accessibility: WCAG 2.1 AA compliance with automated testing
- Performance: Lighthouse optimization with performance budgets
- Testing: 370+ automated tests with 100% pass rate
- Node.js: Version 18.0 or higher (Download)
- Package Manager: npm (included with Node.js) or yarn
- Git: For cloning the repository (Download)
- Supabase Account: For database and authentication (Sign up)
-
Clone the repository:
git clone https://github.com/moshehbenavraham/luminaris-quest.git cd luminaris-quest -
Install dependencies:
npm install # or yarn install -
Set up environment variables:
cp .env.example .env
Edit
.envwith your configuration:# Required - Get from your Supabase project settings VITE_SUPABASE_URL=https://your-project.supabase.co VITE_SUPABASE_ANON_KEY=your-anon-key # Required for AI features (when implemented) VITE_OPENAI_API_KEY=your-openai-api-key # Optional - For enhanced features VITE_LEONARDO_API_KEY=your-leonardo-api-key VITE_ELEVENLABS_API_KEY=your-elevenlabs-api-key
-
Set up the database:
# If you have Supabase CLI installed supabase db push # Or manually run the migration SQL in your Supabase dashboard # See docs/migrations/ for migration files
-
Start the development server:
npm run dev
The app will be available at
http://localhost:5173
| Variable | Description | Where to Get |
|---|---|---|
VITE_SUPABASE_URL |
Your Supabase project URL | Supabase Dashboard → Settings → API |
VITE_SUPABASE_ANON_KEY |
Supabase anonymous key | Supabase Dashboard → Settings → API |
| Variable | Description | Purpose |
|---|---|---|
VITE_OPENAI_API_KEY |
OpenAI API key | Dynamic narrative generation |
VITE_LEONARDO_API_KEY |
Leonardo.AI API key | Scene image generation |
VITE_ELEVENLABS_API_KEY |
ElevenLabs API key | Voice narration |
VITE_DEBUG_MODE |
Enable debug logging | Development debugging |
The application requires a Supabase database with specific tables and policies. Choose one of these setup methods:
# Install Supabase CLI
npm install -g supabase
# Login to Supabase
supabase login
# Link to your project
supabase link --project-ref your-project-id
# Push migrations
supabase db push- Go to your Supabase Dashboard → SQL Editor
- Copy and paste the contents of
docs/migrations/PRODUCTION_MIGRATION_EXECUTED_2025-06-17.sql - Run the migration
After setup, verify these tables exist:
game_states- Stores player progressjournal_entries- Stores therapeutic journal entries
Node.js Version Error
# Check your Node.js version
node --version
# If below 18.0, update Node.js
# Visit https://nodejs.org/ for the latest versionDatabase Connection Issues
- Verify your Supabase URL and anon key are correct
- Check that your Supabase project is active
- Ensure RLS policies are properly configured
Build Errors
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
# Clear Vite cache
npm run dev -- --forcePort Already in Use
# Use a different port
npm run dev -- --port 3000For more detailed troubleshooting, see docs/troubleshooting/faq.md.
- Dynamic Relationship: Core mechanic tracking player's bond with their guardian spirit (0-100)
- Meaningful Progression: Trust level affects combat effectiveness and story outcomes
- Milestone Rewards: Unlock new abilities and story content at trust thresholds (25, 50, 75, 100)
- Therapeutic Metaphor: Represents building trust in therapeutic relationships
- Therapeutic Combat: Transform traditional RPG combat into emotional regulation practice
- Dual Resources: Light Points (positive emotions) and Shadow Points (challenges to overcome)
- Four Combat Actions:
- Illuminate: Offensive action using awareness to overcome fears
- Reflect: Transform challenges into wisdom and growth
- Endure: Defensive patience that builds resilience over time
- Shadow Embrace: High-risk integration of difficult emotions
- Shadow Manifestations: Battle internal struggles like Doubt, Isolation, Overwhelm, and Past Pain
- Combat Reflection: Post-battle therapeutic processing and insight generation
🔄 Combat System Rebuild in Progress: The project currently contains TWO combat systems running in parallel:
- Original System (
src/components/combat/) - The initial implementation with known issues- New System (
src/features/combat/) - Complete mobile-first rebuild with proper architecture- Feature Flag: The new system is enabled by default. Add
?legacyCombat=1to URL to use the original system- Status: New system is feature-complete and in testing phase (see docs/contributing/roadmap.md for details)
- Diverse Scene Types: Social, skill, combat, journal, and exploration scenarios
- Progressive Difficulty: Carefully balanced therapeutic challenges across 4 complete cycles
- Dice-Based Mechanics: d20 rolls against difficulty checks with meaningful outcomes
- Branching Narratives: Choices that matter and reflect real-world coping strategies
- Therapeutic Reflection: AI-guided prompts for processing experiences and emotions
- Two Journal Types:
- Milestone Journals: Celebrate achievements and growth moments
- Learning Journals: Process setbacks and extract wisdom from challenges
- Full CRUD Operations: Create, read, update, delete with comprehensive edit history
- Visual Distinction: Clear UI differences between journal entry types
- Persistent Storage: Secure cloud storage with user authentication
- Comprehensive Analytics: Track trust progression, scene completion, and journal insights
- Achievement System: Meaningful milestones that celebrate therapeutic progress
- Visual Progress: Charts and graphs showing growth over time
- Export Capabilities: Download progress reports for sharing with therapists
- WCAG 2.1 AA Compliance: Full keyboard navigation and screen reader support
- Multiple Input Methods: Mouse, keyboard, and touch-friendly interfaces
- Visual Accessibility: High contrast modes and customizable text sizes
- Cognitive Accessibility: Clear navigation and consistent interaction patterns
- Mobile-First: Optimized for smartphones and tablets
- Cross-Platform: Works seamlessly on desktop, tablet, and mobile devices
- Progressive Enhancement: Core functionality works without JavaScript
- Performance Optimized: Fast loading with image optimization and code splitting
- Therapeutic Soundscapes: Custom-composed background music for emotional regulation
- Combat Sound Effects: Audio feedback for actions and therapeutic insights
- Visual Alternatives: All audio content has visual equivalents for accessibility
- Customizable Audio: Volume controls and audio preferences
- End-to-End Security: All user data encrypted in transit and at rest
- HIPAA-Aware Design: Built with healthcare privacy standards in mind
- User Control: Complete control over data sharing and deletion
- Anonymous Options: Play without creating an account for maximum privacy
- Secure Login: Email/password authentication with optional social providers
- Password Recovery: Secure password reset via email
- Session Management: Automatic logout and secure session handling
- Multi-Device Support: Sync progress across devices securely
The application follows a modern, scalable architecture designed for maintainability, performance, and therapeutic effectiveness.
src/
├── components/ # Reusable UI components
│ ├── atoms/ # Basic building blocks (ImpactfulImage, etc.)
│ ├── combat/ # Combat system components
│ ├── layout/ # Navigation and layout components
│ ├── organisms/ # Complex components (AudioPlayer)
│ └── ui/ # Shadcn/UI component library
├── engine/ # Core game logic
│ ├── combat-engine.ts # Combat mechanics and AI
│ ├── scene-engine.ts # Story progression and dice mechanics
│ └── combat-balance.ts # Balance testing and validation
├── hooks/ # Custom React hooks
│ ├── useCombat.ts # Combat state management
│ ├── useCombatSounds.ts # Audio integration
│ └── useImpactfulImage.ts # Image optimization
├── pages/ # Route components
│ ├── Home.tsx # Landing and authentication
│ ├── Adventure.tsx # Main gameplay interface
│ ├── Progress.tsx # Progress tracking and analytics
│ └── Profile.tsx # User profile and settings
├── store/ # State management
│ └── game-store.ts # Zustand store with persistence
├── integrations/ # External services
│ └── supabase/ # Database and authentication
├── data/ # Static game data
│ ├── shadowManifestations.ts # Combat enemy definitions
│ ├── audioPlaylist.ts # Music and sound effects
│ └── imageRegistry.ts # Optimized image assets
└── lib/ # Utility functions and configurations
├── database-health.ts # Database monitoring
├── performance-monitoring.ts # Performance tracking
└── utils.ts # Common utilities
- Atomic Design: Components organized by complexity (atoms → molecules → organisms)
- Composition over Inheritance: Flexible component composition with props
- Single Responsibility: Each component has one clear purpose
- Prop Drilling Prevention: Context and state management for shared data
- Zustand Store: Centralized state with persistence and hydration safety
- Immutable Updates: All state changes follow immutability patterns
- Optimistic Updates: UI updates immediately with rollback on failure
- Selective Subscriptions: Components only re-render when relevant state changes
User Action → Component → Hook → Store → Engine → Database
↑ ↓
UI Update ← Component ← Hook ← Store ← Response ← Database
- Safety: All interactions designed to be emotionally safe
- Progress: Every action contributes to therapeutic progress
- Reflection: Built-in opportunities for self-reflection and insight
- Empowerment: User maintains control over their therapeutic journey
- Code Splitting: Lazy loading of route components
- Image Optimization: WebP/AVIF formats with responsive sizing
- Bundle Analysis: Regular monitoring of bundle size and dependencies
- Caching Strategy: Intelligent caching of static assets and API responses
- Semantic HTML: Proper HTML structure for screen readers
- ARIA Integration: Comprehensive ARIA labels and roles
- Keyboard Navigation: Full keyboard accessibility for all interactions
- Focus Management: Logical focus flow and visual focus indicators
- PostgreSQL: Robust relational database with JSONB for flexible data
- Row Level Security: User data isolation at the database level
- Optimized Queries: Indexed columns for common query patterns
- Backup Strategy: Automated backups with point-in-time recovery
- RESTful Patterns: Consistent API design following REST principles
- Type Safety: Full TypeScript types generated from database schema
- Error Handling: Comprehensive error handling with user-friendly messages
- Rate Limiting: Protection against abuse with graceful degradation
- Unit Tests: Individual component and function testing
- Integration Tests: Component interaction and data flow testing
- Accessibility Tests: Automated WCAG compliance testing
- Performance Tests: Bundle size and runtime performance monitoring
- TypeScript: Zero compilation errors required
- ESLint: Zero linting warnings required
- Test Coverage: Minimum 80% code coverage maintained
- Accessibility: WCAG 2.1 AA compliance verified
| Command | Description | Usage |
|---|---|---|
npm run dev |
Start development server | Development with hot reload |
npm run build |
Build for production | Creates optimized production build |
npm run build:dev |
Build in development mode | Build with development optimizations |
npm run preview |
Preview production build | Test production build locally |
npm run lint |
Run ESLint | Check code quality and standards |
npm run format |
Format code with Prettier | Auto-format all code files |
npm test |
Run tests with Vitest | Execute test suite |
npm run test:coverage |
Run tests with coverage | Generate coverage reports |
npm run optimize-images |
Optimize image assets | Convert and compress images |
# Clone and setup
git clone https://github.com/moshehbenavraham/luminaris-quest.git
cd luminaris-quest
npm install
# Setup environment
cp .env.example .env
# Edit .env with your configuration
# Start development
npm run dev# Create feature branch
git checkout -b feature/your-feature-name
# Make changes and test
npm run lint # Check code quality
npm test # Run tests
npm run build # Verify build works
# Commit changes
git add .
git commit -m "feat: add your feature description"# Before submitting PR
npm run lint --fix # Fix linting issues
npm run format # Format code
npm test # Ensure all tests pass
npm run build # Verify production build- TypeScript: Strict typing required for all components and functions
- ESLint: Zero warnings policy - all linting issues must be resolved
- Prettier: Consistent code formatting across the entire codebase
- Imports: Use absolute imports with
@/prefix for src directory
- Atomic Design: Follow atoms → molecules → organisms → pages hierarchy
- Single Responsibility: Each component should have one clear purpose
- Props Interface: Define clear TypeScript interfaces for all props
- File Size: Keep components under 250 lines; split into subcomponents if necessary
- Naming: Use PascalCase for components, camelCase for functions and variables
- Test Coverage: Minimum 80% coverage for new code
- Test Types: Unit tests for functions, integration tests for components
- Accessibility: Include accessibility tests using jest-axe
- Performance: Test critical user paths for performance regressions
- WCAG 2.1 AA: All components must meet accessibility standards
- Semantic HTML: Use proper HTML elements and structure
- Keyboard Navigation: Full keyboard accessibility for all interactions
- Screen Readers: Test with screen reader software
- Focus Management: Logical focus flow and visible focus indicators
- VS Code: Recommended with ESLint, Prettier, and TypeScript extensions
- Cursor: Supported with custom rules in
.cursor/rules/ - Windsurf: Supported with custom rules in
.windsurf/rules/
- React DevTools: For component inspection and state debugging
- Vite DevTools: For build and performance analysis
- Supabase Dashboard: For database queries and real-time data
- Browser DevTools: For performance profiling and accessibility testing
- Lighthouse: Regular performance audits
- Bundle Analyzer: Monitor bundle size and dependencies
- Web Vitals: Track Core Web Vitals metrics
- Performance Budget: Enforce performance constraints
- Read docs/contributing/index.md for detailed guidelines
- Check docs/contributing/roadmap.md for current priorities
- Review docs/architecture/components.md for architecture overview
- Understand the therapeutic goals and user safety considerations
- Fork the repository and create a feature branch
- Implement your changes following the development standards
- Test thoroughly including accessibility and performance
- Document any new features or API changes
- Submit PR with clear description and testing instructions
- Functionality: Does the code work as intended?
- Quality: Does it follow coding standards and best practices?
- Testing: Are there adequate tests with good coverage?
- Accessibility: Does it maintain WCAG 2.1 AA compliance?
- Performance: Does it maintain or improve performance?
- Therapeutic Value: Does it align with therapeutic goals?
- README.md - Project overview, getting started guide, and feature documentation
- docs/troubleshooting/faq.md - Frequently asked questions, troubleshooting, and setup guidance
- docs/contributing/index.md - Development guidelines, coding standards, and contribution workflows
- docs/contributing/code-of-conduct.md - Community guidelines and behavioral expectations
- docs/CHANGELOG.md - Version history, notable changes, and release notes
- docs/architecture/components.md - Architecture overview, component relationships, and build priorities
- docs/architecture/database.md - Database table structures, relationships, and RLS policies
- docs/api/index.md - Complete API reference, data structures, and integration guides
- docs/architecture/environments.md - Multi-environment setup and deployment strategy
- docs/contributing/roadmap.md - Comprehensive development roadmap and project management
- docs/guides/deployment.md - Comprehensive deployment guide for all environments
- docs/migrations/ - Database migration files and execution history
PRODUCTION_MIGRATION_EXECUTED_2025-06-17.sql- Production database schema
- netlify.toml - Netlify deployment configuration
- docs/contributing/security.md - Comprehensive security documentation, practices, and compliance
- Privacy Policy - User privacy protection and data handling practices (planned)
- docs/guides/testing.md - Comprehensive testing strategies, frameworks, and best practices
- docs/archive/MILESTONE_FIX_SUMMARY.md - Critical bug fix documentation and lessons learned
- LICENSE - MIT License for codebase
- licenses/ - Comprehensive licensing documentation
OGL.txt- Open Game License for RPG contentthird-party.md- External dependencies and attributions
- eslint.config.js - ESLint rules and code quality standards
- .prettierrc - Prettier code formatting configuration
- .prettierignore - Files excluded from Prettier formatting
- tsconfig.json - Main TypeScript configuration
- tsconfig.app.json - Application-specific TypeScript settings
- tsconfig.node.json - Node.js TypeScript configuration
- vite.config.ts - Vite build tool configuration
- tailwind.config.ts - Tailwind CSS styling configuration
- postcss.config.js - PostCSS processing configuration
- components.json - Shadcn/UI component library configuration
- package.json - Dependencies, scripts, and project metadata
The documentation follows a hierarchical structure:
- Interactive Scenario Selection: Users choose narrative paths that echo real-world emotional challenges
- AI-Generated Visuals: Story moments enhanced with fantasy art (Leonardo.AI integration planned)
- Immersive AI Voice Narration: Dynamic storytelling using voice synthesis (ElevenLabs integration planned)
- Therapeutic Gameplay Mechanics: Mini-tasks and choices designed for resilience, healing, and growth
- Original Music Integration: Curated tracks to enhance emotional immersion
- Code: MIT License
- Game Content: Open Game License (OGL) / Open RPG Creative (ORC)
- Pathfinder 2e: Used under ORC License (excludes Product Identity)
See LICENSE and licenses/ directory for detailed license information.
We welcome contributions! Please read our guidelines:
- Read Documentation: Check
docs/contributing/index.mdfor detailed guidelines - Follow Standards: Adhere to TypeScript strict mode and component guidelines
- Test Changes: Ensure all tests pass and no TypeScript errors
- Respect Architecture: Follow the established component structure and patterns
- Repository: GitHub
- Community: Skool Community
- Supabase: Backend and authentication platform
- Therapeutic Purpose: Luminari's Quest is designed as a supplemental tool to support healing and growth. It is not a replacement for professional mental health care.
- Target Audience: Designed for young adults (18-25) who have experienced parental loss and homelessness during their teenage years.
- Development Environment: Currently in active development with ongoing database schema implementation.
- ✅ Core application architecture complete
- ✅ Component structure refactored and improved
- ✅ TypeScript compilation errors resolved
- 🔄 Combat System Rebuild: New mobile-first combat system (
src/features/combat/) running in parallel with original (src/components/combat/)- New system enabled by default, use
?legacyCombat=1for original - Phases 1-4 complete, Phase 5 (Testing & Polish) in progress
- New system enabled by default, use
⚠️ Database schema implementation in progress- 🔄 Supabase integration being finalized
- 📋 AI service integrations planned for future releases
- Read the FAQ - Common questions and setup help
- Review Contributing Guidelines - Development standards and workflow
- Explore the Architecture - Understand the system design
- Check Current Priorities - See what needs work
- Try the Live Demo - Experience the therapeutic journey
- Read About Our Mission - Understand our therapeutic approach
- Explore Features - Discover what makes this special
- Join the Community - Connect with others
- Quick Start Guide - Get up and running
- API Documentation - Technical reference
- Testing Guide - Quality assurance
- Security Documentation - Security practices
🚨 CRITICAL: TWO COMBAT SYSTEMS EXIST
- NEW System ✅:
/src/features/combat/- Active development, default behavior - OLD System ❌:
/src/components/combat/- DEPRECATED, only with?legacyCombat=1 - See
docs/archive/COMBAT_MIGRATION_GUIDE.mdfor full details
Thank you for your interest in Luminari's Quest! Together, we're creating a meaningful therapeutic experience that can help young adults on their healing journey.
Last updated: December 2024