Puzzle Mastermind is a Next.js 16 app that bundles a set of puzzle solvers and game strategy tools behind a single interface. It began as a Wordle helper, but the codebase now includes solvers for geography, word games, math puzzles, and strategy engines for board and card games.
The project uses:
- Next.js 16 App Router
- React 19
- TypeScript
- Tailwind CSS 4 tooling with PostCSS
- Route Handlers for API-style solver endpoints
The UI exposes a collection of focused tools:
- Wordle Solver
- Globle Solver
- Spelling Bee Solver
- Nerdle Solver
- Duotrigordle experimental route
- Tic Tac Toe perfect-play helper
- Connect 4 analyzer
- Blackjack strategist
- Texas Hold'em equity estimator
Most of the logic lives directly in route handlers or client-side components rather than in a large shared engine. That keeps each tool self-contained and easy to inspect.
app/
api/
solve/ Wordle solver API
globle/ Globle solver API
spelling-bee/ Spelling Bee solver API
nerdle/ Nerdle solver API
duotrigordle/ Experimental Duotrigordle API
wordle/ Wordle UI
globle/ Globle UI
spelling-bee/ Spelling Bee UI
nerdle/ Nerdle UI
tic-tac-toe/ Tic Tac Toe UI
connect-4/ Connect 4 UI
blackjack/ Blackjack UI
poker/ Texas Hold'em UI
components/ Shared UI pieces such as the footer
data/
borders.json Normalized country border adjacency data
scripts/
buildBorders.ts Helper for generating border relationships
words.json Five-letter word list for Wordle-style solvers
spelling_bee_words.txt Dictionary used by the Spelling Bee solver
country_borders.csv Raw border dataset used to derive adjacency data
This matches the App Router conventions in Next.js 16: app/page.tsx defines the home route, app/layout.tsx defines the root layout, and app/api/**/route.ts files define route handlers for solver endpoints.
The root layout sets the app-wide fonts and metadata:
// app/layout.tsx
export const metadata: Metadata = {
title: "Create Next App",
description: "Generated by create next app",
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" className="...">
<body className="min-h-full flex flex-col">{children}</body>
</html>
);
}The home page is a client component that renders a searchable launcher for the solver pages. Each card links to a dedicated route under app/.
Route handlers use NextRequest and NextResponse from next/server. They read JSON input from the request body, compute a filtered answer set, rank the remaining candidates, and return structured JSON for the UI.
The Wordle solver does three things:
- Computes Wordle-style feedback for a guess against a candidate solution.
- Filters the possible answer list to only words that match the feedback history.
- Ranks candidate guesses using entropy, worst-case branch size, and letter diversity.
The feedback function is a standard two-pass implementation:
function getFeedback(guess: string, solution: string): string {
let feedback = Array(5).fill("b");
let sol = solution.split("");
let g = guess.split("");
for (let i = 0; i < 5; i++) {
if (g[i] === sol[i]) {
feedback[i] = "g";
sol[i] = "";
g[i] = "";
}
}
for (let i = 0; i < 5; i++) {
if (g[i] && sol.includes(g[i])) {
feedback[i] = "y";
sol[sol.indexOf(g[i])] = "";
}
}
return feedback.join("");
}The ranking stage measures:
- worst-case bucket size for each guess
- entropy of the feedback distribution
- number of unique letters in the guess
- whether the guess is still a valid solution
It also changes strategy by game stage:
- early game: favor exploration and information gain
- mid game: balance information and solution likelihood
- late game: favor actual answers
In practice, this means the solver does not blindly maximize entropy every turn. It shifts from search-heavy to solve-heavy as the candidate pool shrinks.
The Globle solver combines centroid distance estimates with country border adjacency.
The implementation loads:
- a hardcoded map of country centroids
data/borders.jsonfor adjacency relationships
The important idea is that it narrows candidates from two directions:
- geometric proximity to the hidden country
- whether borders are consistent with the clue history
That makes it behave more like a geography constraint solver than a simple lookup table.
The Spelling Bee route loads the word list from spelling_bee_words.txt, caches it in memory, and then filters for words that obey the puzzle rules:
- at least 4 letters
- must include the center letter
- may only use the 7 allowed letters
For each valid word, it computes:
- score
- pangram flag
- palindrome flag
- word length
Scoring follows the NYT pattern:
- 4-letter words score 1
- longer words score by length
- pangrams get a 7-point bonus
The Nerdle route is a brute-force candidate generator plus feedback filter.
It generates valid equations of the form:
A op B = CA op B op C = D
Then it filters them against feedback history and scores survivors by unique character count.
Key constraints enforced by the generator:
- only digits and
+ - * / - integer-only results
- no division by zero
- no invalid leading zeros
- total equation length must match the 8-character Nerdle format
This is intentionally pragmatic: it prefers a fully valid candidate space over a more abstract symbolic algebra engine.
The Tic Tac Toe solver uses full minimax search on a 3x3 board. Every legal move is explored recursively until a win, loss, or draw is found.
The implementation returns:
10for an X win-10for an O win0for a draw
This is a complete solution for the game because the state space is small enough to exhaustively search.
Connect 4 uses minimax with alpha-beta pruning and a heuristic board evaluator.
The evaluation function rewards:
- center-column control
- 2-in-a-row and 3-in-a-row threats
- immediate wins
It penalizes:
- opponent threats
- losing positions
Search depth changes dynamically based on board fullness:
- more empty spaces means shallower search
- fewer empty spaces means deeper search
That keeps the UI responsive while still improving accuracy late in the game.
The Blackjack tool is a rule-based basic strategy helper. It does not simulate every deck composition; it applies a deterministic strategy table based on:
- hand total
- whether the hand is soft
- whether the hand is a pair
- dealer upcard
It also shows a simple bust-probability estimate and a dealer bust-probability reference table.
That makes it useful as a fast decision aid rather than a full card-counting engine.
The poker tool does three jobs:
- evaluates the current made hand
- classifies the starting hand
- estimates equity with Monte Carlo simulation
The equity engine:
- builds a full 52-card deck
- removes known hole and community cards
- samples random remaining cards
- evaluates both hands across 2,000 iterations
The hand evaluator detects standard hand classes:
- high card
- one pair
- two pair
- three of a kind
- straight
- flush
- full house
- four of a kind
- straight flush
It also detects a few common draw states, such as flush draws and simple straight draws, and explains them in plain language.
The solver APIs are built with POST route handlers in app/api/**/route.ts:
import { NextRequest, NextResponse } from "next/server";
export async function POST(req: NextRequest) {
const body = await req.json();
// validate input
// run solver logic
return NextResponse.json({ ...result });
}This keeps the UI thin and makes each solver consumable as an HTTP endpoint.
The Spelling Bee solver caches the dictionary in module scope so repeated requests do not reread the file:
let cachedWords: string[] | null = null;
function getWords() {
if (cachedWords) return cachedWords;
const fileContent = fs.readFileSync(filePath, "utf-8");
cachedWords = fileContent
.split(/\r?\n/)
.map((w) => w.trim().toLowerCase())
.filter((w) => w.length >= 4);
return cachedWords;
}The Wordle solver adapts scoring weights as the candidate pool shrinks:
if (size > 20) {
score = entropy * 2 + diversity * 1.5 - worstCase * 1.2 + isSolution * 0.2;
} else if (size > 8) {
score = entropy * 1.5 + diversity * 0.5 - worstCase * 1.5 + isSolution * 1.5;
} else {
score = entropy * 0.5 - worstCase * 2 + isSolution * 5;
}That kind of stage-aware weighting is the main reason the solver feels responsive in both early and endgame states.
- Node.js 20 or newer
- npm
npm installnpm run devOpen http://localhost:3000 after the server starts.
npm run build
npm run start
npm run lint- The UI styling is mostly page-local and intentionally custom rather than centralized in a shared design system.
- Solver quality varies by game because each tool uses a different algorithmic approach.
- The Duotrigordle route is explicitly experimental.
- There is no formal automated test suite yet.
- The app still has some scaffold-origin defaults that can be cleaned up over time, including metadata in the root layout.
- add solver correctness tests and API route tests
- extract repeated layout and card styling into reusable components
- benchmark solver quality and response times
- improve metadata, SEO, and social previews
- document dataset provenance more explicitly
Contributions were made by Kamalesh Motamarri, Pughazhendi Saravanan, and Aditya Nair.