Letter Golf¶
Status: Implemented product specification. The platform roadmap owns current delivery status.
Audience: Product, design, engineering, QA, and support.
Technical references: Lexical and Game Architecture and Data Layout and Persistence.
Version history¶
- 0.1: Initial version (JS)
Overview¶
From a list of letters, the user must make words that use up all the letters.
Gameplay¶
Initially the user is presented with a list of 5 distinct letters (configurable via TargetVisibleLetterCount), with counts, and a count of allowed wildcards.
The user must spell words to use up all the letters. The words that have been spelled so far are displayed in a list, and may be deleted. There are no restrictions on the length of the words, but they all must be valid English words according to a dictionary hosted on the backend.
Played-word history UI¶
Played words flow horizontally first and wrap into additional centered rows in both active and completed games. During active play, each word and its remove control stay together as one item; completed words are read-only and show no removal affordance.
Most successful plays use no more than five or six words, so the current adjacent remove icon is
adequate and denser controls are not a near-term requirement. If longer histories become common,
a possible compact treatment is to make the word itself the remove button and overlay a small
circled X badge at its upper-right corner. That treatment must preserve a sufficiently large
touch target, expose an explicit accessible name such as Remove BAND, remain keyboard operable,
and avoid implying that completed words can still be changed.
Hole-in-one¶
Every puzzle is guaranteed to have at least one real word solution using the visible letters plus the wildcard budget (the "lax" hole-in-one). Additionally, a puzzle may have a solution using only the visible letters with zero wildcards (the "strict" hole-in-one), but this is not guaranteed—it's an incidental property, signaled informationally when it occurs.
Open questions¶
- Should we include "par" in the user interface?
- Do we want a count of wildcards, or just subtract from your score if you use letters that aren't in the list?
Daily Puzzles¶
Every calendar day (Pacific Time) has a single global puzzle shared with all players. The puzzle is generated and persisted on the first request of the day; all subsequent requests that same day return the identical puzzle.
Puzzle key format¶
Persisted puzzles are identified by a puzzleKey in the format:
Examples:
lettergolf|global|2026-08-01— the global daily on August 1, 2026lettergolf|group:abc123|2026-08-01— a group-scoped daily (future feature)
The date portion is always Pacific Time (America/Los_Angeles, converted from TimeProvider.GetUtcNow()),
ensuring all players see the same puzzle regardless of their local time zone.
Endpoint: GET /v1/letter-golf/daily¶
Returns the daily puzzle for the current Pacific date. The response uses the same LetterGolfPuzzleResponse
shape as the ad-hoc /v1/letter-golf endpoint:
{
"id": "lettergolf|global|2026-08-01",
"puzzleKey": "lettergolf|global|2026-08-01",
"puzzle": {
"a": 2,
"b": 1,
"c": 1
},
"numWildcards": 3,
"hasHoleInOne": true,
"hasStrictHoleInOne": false,
"par": null,
"difficultyScore": null
}
On first request of the day (cache miss), the endpoint generates a new puzzle and persists it
to the puzzles Cosmos container. Subsequent requests the same day return the stored puzzle —
idempotent reads (< 1 RU each).
Ad-hoc vs. daily puzzles¶
GET /v1/letter-golf— generates a new random puzzle on every call. ResponsepuzzleKeyisnulland the puzzle is not persisted.GET /v1/letter-golf/daily— returns the same puzzle for everyone for the entire Pacific-time day. ResponsepuzzleKeyis set (e.g."lettergolf|global|2026-08-01") and the puzzle is persisted in Cosmos.
Both endpoints return the same LetterGolfPuzzleResponse DTO shape, so frontend code can treat
them uniformly.
Practice Puzzles¶
Endpoint: POST /v1/letter-golf/practice¶
Generates and persists a brand-new, randomly generated practice puzzle on every call. Unlike the
daily puzzle (which is global and shared), practice puzzles have a unique puzzleKey per call and
can be autosaved, resumed, and submitted via the existing play endpoints (GET /play, PUT /play,
POST /submit). Response includes puzzleKey in the format lettergolf|practice|{shortid}.
Rate-limited (20/min/IP) same as other play endpoints; unauthenticated (anyone can create one). Practice puzzles are configured to auto-expire after 30 days via Cosmos DB per-item TTL.
Puzzle key format¶
Practice puzzle keys follow the format:
Example: lettergolf|practice|a1b2c3d4e5
Endpoint: GET /v1/letter-golf/{puzzleKey}¶
Returns the puzzle definition for any persisted puzzle by its exact puzzleKey (currently used by the frontend to restore a practice puzzle after a page refresh). Public read, unauthenticated, no ownership check - consistent with the rest of this API, where puzzle letters/wildcards/par are not secret (only SeedWord, the solution, is excluded from the response). Returns HTTP 404 if the key doesn't exist, which includes both "never existed" and "TTL-expired" - the frontend treats both identically as an expired-puzzle state. Rate-limited (20/min/IP) same as other play endpoints.
Internal Debug/Admin Endpoints¶
These endpoints are operational tooling only, not part of the public player-facing API. They are
disabled by default (fail closed) and only available if the Admin:DebugKey configuration is set
to a non-empty value (must come from a secret store or environment variable, never from appsettings.json).
Both endpoints require the X-Admin-Key header with the exact configured secret value. Authentication
failures return HTTP 404 (not 401/403), by design, to avoid confirming endpoint existence.
Endpoint: POST /v1/letter-golf/{puzzleKey}/play/reset¶
Deletes the caller's own play for a given puzzle (identified by their userId cookie and the
puzzleKey). Returns HTTP 204 on success. Never deletes an arbitrary user's play — reset is always
scoped to the authenticated caller. Idempotent: resetting a play that doesn't exist is a successful no-op.
Endpoint: GET /v1/letter-golf/{puzzleKey}/solutions¶
Returns all valid dictionary words that alone solve a given puzzle within its wildcard budget, plus
the seed word the puzzle was generated from. Response shape: LetterGolfSolutionsResponse with puzzleKey,
seedWord, and solutions (list of strings). Returns HTTP 200 on success, HTTP 404 on any auth failure
or if the puzzle is not found.
Endpoint: GET /v1/letter-golf/daily/{date}/debug-solutions¶
Returns all valid dictionary words that solve the daily puzzle for a given date, plus the seed word. The date
parameter must be in yyyy-MM-dd format (e.g., 2026-08-17). Gated by the DebugSolutions feature flag
(same flag that gates the per-puzzle solutions endpoint). Unlike the per-puzzle GET /v1/letter-golf/{puzzleKey}/solutions,
this endpoint has no prior-completion requirement — a flagged user can browse any date's solutions
regardless of whether they've completed that day's puzzle yet. Response shape: LetterGolfSolutionsResponse with puzzleKey,
seedWord, and solutions (list of strings). Returns HTTP 404 if the flag is disabled, the date hasn't been pre-generated,
or the date is malformed. Spoiler consequence: browsing a date's solutions sets PlayEntity.SolutionsViewedBeforeCompletion = true
on the caller's play for that date (creating a pre-spoiled play stub if none exists), which excludes that play from personal
stats/streaks if/when it's later completed — same treatment as practice-mode plays. Group standings are not affected by this flag.
Endpoint: POST /v1/letter-golf/daily/pregenerate¶
Ensures the next 14 calendar days of global daily puzzles are generated and available. Requires the X-Admin-Key header
(same authentication as POST /v1/letter-golf/{puzzleKey}/play/reset). Idempotent: each date is generated only if missing;
a steady-state run with all dates already pre-generated completes quickly. Continues past per-date failures (logs errors but
doesn't abort the entire operation). Response shape: {horizonDays: 14, successCount: N} where successCount is the number
of dates successfully ensured present (not the count of newly-created puzzles). Returns HTTP 200 on success, HTTP 404 on
auth failure (key missing/wrong/unconfigured). Normally called automatically by a scheduled Azure Container Apps Job
(tf/backend/pregeneration_job.tf, daily at 09:00 UTC), but can be triggered manually by an operator as an escape hatch
to force pre-generation at any time (e.g., for urgent playtest prep or to recover from a missed scheduled run).
Daily and Practice Modes (Player-Facing)¶
The Letter Golf interface offers two play modes, selectable via a toggle in the game header.
Daily Mode¶
Every player sees the same global daily puzzle each day (Pacific-time reset at midnight). Daily puzzles are persistent and shared, so you can return to an in-progress daily puzzle from a previous session and resume where you left off. A live countdown timer shows when the puzzle resets to the next day's puzzle. Since there is only one daily puzzle per day, daily mode is ideal for social competition — all players compete on the same puzzle at the same time.
Practice Mode¶
Practice mode generates a fresh, randomly-selected puzzle on demand. Each practice puzzle is unique, persistent, and playable anytime — independent of the daily Pacific-time date and unshared with other players. You can save and resume a practice puzzle, just like the daily puzzle. Practice puzzles intentionally never contribute to stats or streaks, so they are purely for solo practice without social implications. Switching away from a practice puzzle with unsaved progress (words entered but not yet submitted) will prompt you to confirm — this avoids accidentally discarding work. Once you switch modes, any in-progress practice words are permanently cleared; only submitted plays are preserved.
Future work: the "Best Daily score" line shown on a Practice win reads the player's shared, Daily-only
bestScorestat (Practice plays never update it - see Scoring/Stats section). A genuinely practice-scoped best score or average is not built yet.
Mode Switching¶
Clicking the mode toggle at the top of the game screen switches between Daily and Practice modes.
- Switching to Practice fetches a brand-new puzzle, clears the board, and starts a fresh board. Since the puzzle is generated on demand (and the backend may need to cold-start - see Technical section below), a loading skeleton with a spinner is shown in place of the board until the new puzzle arrives, so the page never looks hung.
- Switching to Daily restores the original daily puzzle and any previously saved play state for that day. If you made progress on the daily puzzle, continued it elsewhere, then switched back, your words are restored.
- Unsaved Practice progress is discarded with confirmation when switching away from an incomplete practice puzzle.
- Practice puzzles are addressable by URL (
?mode=practice&puzzle={puzzleKey}), so refreshing the page while on a practice puzzle restores that exact puzzle and its saved progress instead of reverting to Daily. If the puzzle has expired (30-day TTL) or the key is invalid, a friendly "This practice puzzle has expired" message offers to start a new one or switch to Daily. - Completing a Practice puzzle shows a "Practice complete" summary with two actions: start another practice puzzle, or switch to today's Daily. Practice completions never show a share prompt (a recipient couldn't play the same practice puzzle) and never show a streak.
Scoring¶
The goal is the lowest score (lower is better). Scoring rules:
- One-word completion: If you finish the puzzle with a single word, your score is 1 point, even if that word used one or more wildcards. (A strict hole-in-one is the special case where the single-word solution uses zero wildcards; it's informational only.)
- All other completions: Score = number of words used + number of wildcards actually used. Wildcards are shown in summaries but do not change the one-word exception above.
Example: if you complete a puzzle with 3 words and used 1 wildcard across those plays, your score is 3 + 1 = 4 points. If you complete the puzzle with a single word (even using wildcards), your score is 1.
Sharing¶
I got a score of 2 playing Letter Golf! See if you can beat my score! https://[our url]/lettergolf
Playtesting¶
Everyone who playtests should include a section in this area with notes. Divide these notes by versions of the game.
Technical¶
Notes about any technical decisions made.
-
Letter Golf shares normalized, moderated, versioned lexical content with other games while retaining its own admission profiles, count-signature index, frequency data, generator, and validation rules. See Lexical and Game Architecture for the durable ownership model and the compatibility migration away from
IWords/MultiDict. -
The backend Container App scales to zero after 30 minutes of inactivity (
cooldown_period_in_secondsintf/backend/container_app.tf, raised from Azure's 5-minute default) since it builds large in-memory word-list dictionaries on startup, making cold starts slow. A request that hits a scaled-to-zero backend (most likely the on-demandPOST /practicepuzzle generation) can take noticeably longer than a warm request; the frontend shows a loading skeleton for this reason rather than assuming the request will always be fast. - A pre-generated Daily puzzle does not exercise the generator, so its first final submission
could previously be the request that downloaded and aggregated the validation dictionaries.
After the gameplay view renders, the frontend now starts an idempotent
POST /v1/letter-golf/validation/warmuprequest in parallel with local dictionary seeding. If a player solves unusually quickly, submission waits for that already-running browser request; a failed warm-up falls through to normal submission and does not block play. Backend word-source and aggregate initialization are single-flight, retry after transient failures, and remain process-local to each Container Apps replica. Practice generation already builds the generator-only count-trie and frequency table, so Daily warm-up deliberately initializes only the dictionary required for authoritative word validation.