King's Path - Chess Conversion Puzzle

Overview

King's Path is a strategic 6x6 grid puzzle game built with React, Express, and TypeScript. The core gameplay involves moving a single King piece across a chess-themed board, where the King converts tiles to "King tiles" and inherits movement abilities from the pieces it lands on. Players must strategically navigate the board to convert all 36 tiles to complete the puzzle.

The application is a full-stack web game with a React frontend using Vite, an Express backend API, and optional PostgreSQL database integration for tracking game attempts and player statistics.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework & Build Tool

• React 18 with TypeScript for type-safe component development
• Vite as the build tool and development server, chosen for fast HMR and optimized production builds
• Wouter for lightweight client-side routing (only two routes: Home and Puzzle)

UI Component System

• Shadcn/ui component library using Radix UI primitives
• TailwindCSS v4 for styling with custom theme configuration
• Custom design system with royal dark theme (gold/amber primary colors, deep slate backgrounds)
• Three custom fonts: Inter (sans), Playfair Display (serif), Cinzel (display/headings)

State Management

• TanStack Query (React Query) for server state management and API caching
• Local React state for game logic and UI interactions
• Custom hooks for mobile detection and toast notifications

Game Logic Architecture

• Pure TypeScript module (chess-logic.ts) handles all game rules:
  • Board generation with randomized piece placement
  • Movement validation based on chess piece rules (King, Queen, Rook, Bishop, Knight, Pawn)
  • Path conversion tracking (tiles convert during movement, except Knight jumps)
  • Win condition checking (all tiles converted to Kings)
  • Optional board solver for optimal path calculation

Animation & Visual Effects

• Framer Motion for board tile animations and transitions
• Canvas Confetti for win celebration effects
• Custom CSS animations using TailwindCSS animate utilities

Backend Architecture

Server Framework

• Express.js with TypeScript for API endpoints
• HTTP server (no WebSocket implementation currently)
• Development mode uses Vite middleware for HMR
• Production mode serves pre-built static files

API Design

• RESTful endpoints for game attempt persistence:
  • POST /api/game-attempts - Save game completion data
  • GET /api/game-attempts/:userId - Retrieve user's game history
  • GET /api/game-stats/:userId - Fetch aggregated statistics
• Request validation using Zod schemas
• Simple error handling with standardized JSON responses

Storage Layer Abstraction

• Interface-based storage design (IStorage) allows swapping implementations
• In-memory storage (MemStorage) for development/demo mode
• Database storage support via Drizzle ORM (PostgreSQL with Neon serverless)
• Storage includes user management and game attempt tracking

Build Process

• Custom build script using esbuild for server bundling
• Dependency allowlist to reduce cold start times by bundling specific packages
• Separate client and server builds, combined into single dist directory

Database Schema

ORM & Migrations

• Drizzle ORM with PostgreSQL dialect
• Schema-first design with TypeScript types generated from schema
• Zod integration for runtime validation of database inputs

Tables

• users: Basic user management (id, username, password)
• game_attempts: Game session tracking with:
  • Grid size (3, 4, 5, or 6)
  • Move count and completion time
  • Completion status
  • Optional path history (JSON array of positions)
  • Optimal move count from solver for comparison

Data Validation

• Drizzle-Zod generates insert schemas from table definitions
• Type-safe database operations with full TypeScript inference

Project Structure

├── client/               # Frontend React application
│   ├── src/
│   │   ├── components/   # Reusable UI components (shadcn/ui)
│   │   ├── pages/        # Route components (Home, Puzzle)
│   │   ├── lib/          # Utilities and game logic
│   │   └── hooks/        # Custom React hooks
│   ├── index.html        # HTML template with meta tags
│   └── public/           # Static assets
├── server/               # Backend Express application
│   ├── index.ts          # Server entry point
│   ├── routes.ts         # API route definitions
│   ├── storage.ts        # Storage abstraction layer
│   └── db.ts             # Database connection
├── shared/               # Code shared between client/server
│   └── schema.ts         # Drizzle schema and Zod validators
├── migrations/           # Database migration files
└── script/               # Build and deployment scripts

External Dependencies

Database & ORM

• Neon Serverless PostgreSQL (@neondatabase/serverless) - Serverless Postgres database for production
• Drizzle ORM (drizzle-orm, drizzle-kit) - Type-safe ORM with schema management
• Drizzle-Zod - Runtime validation bridge between Drizzle and Zod

Frontend Libraries

• Radix UI - Headless accessible component primitives (20+ components installed)
• TanStack Query - Async state management and caching
• Framer Motion - Animation library for board interactions
• Canvas Confetti - Celebration effects on puzzle completion
• Class Variance Authority - Type-safe CSS variant management
• Wouter - Minimal router (1.3kb alternative to React Router)

Development Tools

• Vite - Fast build tool and dev server
• Replit Plugins - Development banner, runtime error overlay, cartographer for code navigation
• Custom Vite Plugin - Meta image tag updater for OpenGraph/Twitter cards

Build & Deployment

• esbuild - Fast JavaScript bundler for production server code
• tsx - TypeScript execution for development
• Environment variables required:
  • DATABASE_URL - PostgreSQL connection string (optional, falls back to in-memory storage)
  • NODE_ENV - Environment mode (development/production)

Styling

• TailwindCSS v4 - Utility-first CSS framework with custom theme
• Autoprefixer - CSS vendor prefix management
• Google Fonts integration (Cinzel, Inter, Playfair Display)