Ghotidle

A daily word puzzle game with a phonetics twist! Players see an oddly-spelled word (like "ghoti") and must deduce the standard spelling ("fish") using phonetic clues and letter feedback.

The Unique Twist

Unlike traditional Wordle, Ghotidle is a reverse phonetic puzzle:

• The game displays an unconventionally-spelled word (e.g., "GHOTI")
• Players guess the standard spelling (e.g., "fish")
• When correct sounds are guessed, both the guess letters AND the phonetic letters highlight green
• Example: Guessing "trash" highlights "sh" in your guess and "ti" in "GHOTI" (both make the "sh" sound!)

The name comes from the famous example: "ghoti" = "fish"

• gh = "f" (as in "enough")
• o = "i" (as in "women")
• ti = "sh" (as in "nation")

Project Structure

backend/          - Django 4.2 + DRF + PostgreSQL
frontend/         - React 19 + TypeScript
.github/          - Copilot instructions for AI agents

Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+
• PostgreSQL

Backend Setup (PowerShell)

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser  # For admin access
python manage.py runserver  # http://localhost:8000

Frontend Setup (Separate Terminal)

cd frontend
npm install
npm start  # http://localhost:3000

How to Play

1. See the phonetic word displayed at the top (e.g., "GHOTI")
2. Guess the standard spelling - must be a valid dictionary word
3. Receive feedback:
   • Green: Letter in correct position in hidden word
   • Yellow: Letter exists in hidden word, wrong position
   • Gray: Letter not in hidden word
   • Length indicator: Shows if your guess length matches
   • Phonetic highlights: When sounds match (e.g., "sh" ↔ "ti"), both get highlighted
4. 6 attempts to solve the puzzle
5. Daily puzzle changes every 24 hours (NYT Wordle style)

Example Game Flow

Display: "GHOTI" (4 letters)

Guess 1: "trash" (5 letters ✗)
Feedback: t=gray, r=gray, a=gray, s=yellow, h=yellow
Phonetic: "sh" → "ti" highlighted (sound match!)

Guess 2: "fish" (4 letters ✓)
Result: WIN!
Explanation:
  gh → f (enough)
  o → i (women)
  ti → sh (nation)

Setup and Installation

Prerequisites

• Python 3.8+
• Node.js 16+
• PostgreSQL

Backend Setup (PowerShell)

Backend Setup (PowerShell)

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser  # For admin access
python manage.py load_sample_data  # Optional: load sample phonetic patterns
python manage.py runserver  # http://localhost:8000

Frontend Setup (Separate Terminal)

cd frontend
npm install
npm start  # http://localhost:3000

API Endpoints

Word Retrieval

• GET /api/word/daily/ - Today's daily puzzle (phonetic spelling shown, standard hidden)
• GET /api/word/random/ - Random practice word
• GET /api/word/<id>/ - Specific word retrieval

Game Logic

• POST /api/validate/ - Validate guess with letter feedback + phonetic mapping highlights
  • Returns: letter-by-letter feedback, phonetic sound matches, length validation
  • Validates against dictionary (rejects nonsense like "abcdefgh")
  • Provides partial feedback even if length mismatches

User Management (Future)

• POST /api/user/register/ - User registration
• GET /api/user/stats/ - User statistics and leaderboard data

Technologies Used

Backend

• Django 4.2
• Django REST Framework
• Django CORS Headers
• PostgreSQL (user accounts + phonetic patterns)

Frontend

• React 19
• TypeScript 4.9
• Create React App
• Jest + React Testing Library

Database Schema

Three-table structure for phonetic correlations:

1. PhoneticPattern - Letter combinations → sounds (e.g., "gh" → "f" from "enough")
2. Word - Daily puzzles (standard + phonetic spellings, day_number for sequencing)
3. PhoneticComponent - Junction table linking words to their phonetic breakdown

Contributing

For Developers

1. Read AI Instructions: Check .github/copilot-instructions.md for comprehensive architecture details
2. Database: PostgreSQL required (phonetic patterns + future user accounts)
3. Testing: Run npm test (frontend) and python manage.py test (backend)
4. Migrations: Always run makemigrations after model changes

Adding New Words

Through Django admin (http://localhost:8000/admin):

1. Create PhoneticPattern entries (e.g., "gh" → "f", example: "enough")
2. Create Word entry (standard + phonetic spelling, assign day_number)
3. Create PhoneticComponent links (map positions between spellings)

Example: For "ghoti" → "fish":

• Pattern: gh(0)→f(0), o(2)→i(1), ti(3)→sh(2)
• Each component stores positions in both phonetic and standard spellings

Key Features

• Daily puzzle system (NYT Wordle-style: deterministic word selection by date)
• Dictionary validation (only real words accepted)
• Phonetic sound matching (highlights corresponding letters in both guess and display)
• Length-agnostic feedback (provides clues even if guess length is wrong)
• Multiple phonetic spellings (same word can have variants: "ghoti" vs "gheati" for "fish")
• User accounts & leaderboards (planned)
• Game statistics tracking (planned)

Project Conventions

• CORS: Frontend on :3000, backend on :8000 (pre-configured in settings.py)
• Component styling: Each React component has dedicated CSS file (e.g., Board.css)
• Pronunciation format: Simplified notation (e.g., "f-i-sh") not IPA
• Virtual environment: Always activate before backend work (venv\Scripts\activate)
• Daily word logic: word_index = (today - start_date).days % total_words

Common Pitfalls

1. Must activate virtual environment before backend commands
2. PostgreSQL must be running and configured
3. Run migrations after any model changes
4. Backend must be on port 8000, frontend on 3000 (hardcoded)
5. React 19 + TypeScript 4.9 - ensure type annotations match

Documentation

• AI Agent Instructions: .github/copilot-instructions.md - Comprehensive guide for AI coding assistants
• Game Mechanics: Reverse phonetic puzzle design documented above
• Database Schema: Three-table structure for phonetic mappings

Design Philosophy

This game explores the quirks of English phonetics in an accessible, puzzle-like format. By reversing the traditional spelling→phonetics direction, players discover how the same sounds can be represented by wildly different letter combinations. The game is educational while remaining fun and challenging!

Status: Active Development
License: TBD
Maintainer: @cirqt