Word Mastermind

Word Mastermind is a lightweight, self‑hosted web application that implements an endless‑play variant of the popular word puzzle “Wordle”. From a technical standpoint it is a single‑page React front‑end served by an Express/Node.js back‑end that performs word validation, random target selection and status calculation. The core logic is pure JavaScript, which makes it trivial to embed or extend in other Node‑based services.

Key Features

• Endless play – unlike the original Wordle, there is no daily limit; a new random word is chosen for each game session.
• Custom dictionary support – users can drop plain‑text word lists (one word per line) into the dicts folder and reference them via a query string (?dictName=ro-ro-5). The back‑end reads the file on demand and caches it in memory.
• Letter feedback engine – the server implements a deterministic algorithm that returns green, yellow or gray for each letter, mirroring Wordle’s scoring rules.
• Keyboard UI – the front‑end highlights key states (present, absent, unknown) based on all guesses made so far.

Technical Stack

The application ships as a single Docker image exposing port 80, which is then mapped to the host’s 3333. This makes it trivial to run behind a reverse proxy or in Kubernetes as a stateless pod.

Core Capabilities

• API – The server exposes a minimal JSON API (/api/guess) that accepts a word, validates it against the active dictionary and returns an array of status objects. This API can be consumed by custom front‑ends or bots.
• WebSocket support – While not explicitly documented, the repo contains a basic WebSocket handler that could be leveraged for real‑time multiplayer or leaderboard features.
• Extensible dictionary loader – The loadDictionary helper can be overridden to fetch dictionaries from S3, HTTP endpoints or databases, enabling dynamic word lists.

Deployment & Infrastructure

• Self‑hosting – Requires only Node.js 16+ or Docker. No external services are needed.
• Scalability – Stateless design allows horizontal scaling behind a load balancer. The in‑memory cache of dictionaries can be replicated across replicas or persisted to Redis if needed.
• Containerization – The Dockerfile uses a multi‑stage build: the first stage compiles the React app, the second stages copy compiled assets into a lightweight Node image. This keeps final images under 100 MB.

Integration & Extensibility

• Plugin hooks – The codebase exposes a simple hook system (onGuess, beforeServe) that developers can tap into to modify scoring logic or add analytics.
• Webhooks – By configuring a simple POST /webhook endpoint, external services can receive guess events for logging or gamification.
• Custom UI – The front‑end is modular; swapping out the keyboard component or styling is a matter of replacing a single React component.

Developer Experience

• Configuration – All settings (port, dictionary path, word length) are driven by environment variables or query parameters. The README provides clear guidance on both Docker and Node.js runtimes.
• Documentation – The repository contains a concise README, inline comments, and a small set of unit tests that serve as living documentation for the algorithm.
• Community – While the project is small, it has an active GitHub issue tracker and accepts pull requests. Licensing (MIT) allows commercial use without restrictions.

Use Cases

1. Custom word‑learning platforms – Embed Word Mastermind in a language learning app to provide endless practice with user‑supplied vocab lists.
2. Internal team engagement – Deploy on a company intranet to run daily word challenges that encourage collaboration and friendly competition.
3. Educational tooling – Use the API to build interactive lessons in classrooms, integrating with learning management systems.
4. Bots & automation – Leverage the JSON API to create AI solvers or automated testing suites for language models.

Advantages

• Performance – Pure JS logic with minimal I/O gives sub‑10 ms response times per guess.
• Flexibility – No database schema; dictionaries can be swapped on the fly, enabling multi‑language support.
• Licensing – MIT license removes any commercial usage barriers, making it ideal for internal or paid services.
• Simplicity – The entire stack fits comfortably on a Raspberry Pi, making it accessible for hobbyists or edge deployments.

Word Mastermind offers a developer‑friendly, lightweight foundation for building word‑based games or educational tools that require rapid iteration and easy deployment.