🎯 Gekkur - Game Show Emulator

A web application that emulates the Faroese TV game show "Gekkur" - a bingo-style game where winners spin a prize wheel with game theory-based optimal stopping strategies.

🎮 Game Mechanics

• Bingo Component: Complete a 5x5 bingo board to unlock the prize wheel
• Prize Wheel: Spin to win prizes with multipliers (3x, 2x, 1x)
• Special Prizes: Yellow, Red, and Blue Leypurin (always worth stopping for)
• Game Theory: Real-time recommendations on optimal stopping points

🛠️ Tech Stack

• Runtime: Bun
• Language: TypeScript (vanilla, no React)
• Frontend: Vanilla TypeScript + Bulma CSS
• Backend: Hono + Flowcore
• Styling: Bulma CSS Framework

🚀 Quick Start

Prerequisites

• Bun installed
• Node.js 18+ (for compatibility)

Installation

# Clone the repository
git clone <repository-url>
cd geekur

# Install dependencies
bun install

# Start development servers
bun run dev

This will start:

• Frontend: http://localhost:3002
• Backend: http://localhost:3001

Development Commands

# Start both frontend and backend
bun run dev

# Start only frontend
bun run dev:frontend

# Start only backend
bun run dev:backend

# Build for production
bun run build

# Run tests
bun test

# Lint code
bun run lint

📁 Project Structure

geekur/
├── frontend/          # Vanilla TypeScript frontend
│   ├── src/
│   │   ├── components/    # UI components
│   │   ├── services/      # API services
│   │   ├── types/         # TypeScript interfaces
│   │   └── constants/     # Game configuration
│   ├── public/            # Static assets
│   └── dev-server.ts      # Custom Bun dev server
├── backend/           # Hono + Flowcore backend
│   ├── src/
│   │   ├── routes/        # API routes
│   │   ├── services/      # Business logic
│   │   ├── types/         # TypeScript interfaces
│   │   └── constants/     # Game configuration
└── shared/            # Shared types and constants
    ├── types/             # TypeScript interfaces
    └── constants/         # Game configuration

🎯 Development Phases

✅ Phase 1: Project Setup & Core Infrastructure (COMPLETED)

Status: ✅ COMPLETED

What was accomplished:

• ✅ Monorepo structure with Bun workspaces
• ✅ TypeScript configuration for all packages
• ✅ Backend infrastructure with Hono server
• ✅ Frontend infrastructure with vanilla TypeScript
• ✅ Custom Bun development server for frontend
• ✅ Module resolution and build system
• ✅ Basic API routes and services structure
• ✅ Bulma CSS integration
• ✅ Development servers running on ports 3001 (backend) and 3002 (frontend)

Key files created:

• Project configuration (package.json, tsconfig.json)
• Backend server (backend/src/server.ts)
• API routes (backend/src/routes/game.ts, backend/src/routes/statistics.ts)
• Services (backend/src/services/GameLogicService.ts, backend/src/services/FlowcoreService.ts)
• Frontend components (frontend/src/components/)
• Frontend services (frontend/src/services/GameService.ts)
• Shared types and constants
• Custom development server (frontend/dev-server.ts)

🔄 Phase 2: Core Game Logic (IN PROGRESS)

Status: 🔄 READY TO START

Planned features:

• 🔄 Interactive Bingo Board
  • Number marking functionality
  • Win detection (rows, columns, diagonals)
  • Visual feedback for marked numbers
• 🔄 Animated Prize Wheel
  • Smooth spinning animations
  • Visual wheel with all prize slots
  • Pointer and result highlighting
• 🔄 Game State Management
  • Round progression (3 spins max)
  • Game completion handling
  • State persistence
• 🔄 Game Theory Engine
  • Real-time expected value calculations
  • Optimal stopping recommendations
  • Probability analysis

📋 Phase 3: Advanced Features (PLANNED)

Status: 📋 PLANNED

Planned features:

• 📋 Statistics Dashboard
  • Game history tracking
  • Performance metrics
  • Win/loss analytics
• 📋 Simulation Engine
  • Monte Carlo simulations
  • Strategy testing
  • Performance benchmarking
• 📋 Enhanced UI/UX
  • Responsive design improvements
  • Animation enhancements
  • Accessibility features

🚀 Phase 4: Production & Deployment (PLANNED)

Status: 🚀 PLANNED

Planned features:

• 🚀 Flowcore Integration
  • Real data persistence
  • Event tracking
  • Analytics integration
• 🚀 Production Build
  • Optimization and minification
  • Performance tuning
  • Error handling
• 🚀 Deployment
  • Docker containerization
  • CI/CD pipeline
  • Production hosting

🎯 Current Features

✅ Completed Features

• ✅ Project Infrastructure
• ✅ Development Environment
• ✅ Basic API Structure
• ✅ Frontend Framework Setup

🔄 In Development

• 🔄 Interactive Bingo Board
• 🔄 Animated Prize Wheel
• 🔄 Game State Management
• 🔄 Game Theory Engine

📋 Planned Features

• 📋 Statistics Dashboard
• 📋 Simulation Engine
• 📋 Enhanced UI/UX
• 📋 Flowcore Integration
• 📋 Production Deployment

🧮 Game Theory

The app calculates expected values in real-time and recommends when to stop spinning based on:

• Current prize value vs. expected value of continuing
• Special prize (Leypurin) detection (always recommend stopping)
• Probability calculations for each round
• Multiplier system (3x, 2x, 1x)

🔧 Configuration

Environment Variables

Variable	Type	Description	Default	Required
PORT	number	Backend server port	3001
NODE_ENV	enum	Environment mode ("development", "test", "production")	"development"

Game Configuration

Edit shared/constants/GameConfig.ts to customize:

• Bingo board size and number range
• Prize wheel slots and prizes
• Multiplier values
• Special prize configurations

📊 Flowcore Integration

The backend integrates with Flowcore for:

• Game state persistence
• Event tracking
• Statistics and analytics
• Performance monitoring

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Inspired by the Faroese TV game show "Gekkur"
• Built with modern web technologies
• Game theory implementation for optimal decision making