baseline_commit: `961c538`

Story 1.1: Project Foundation & Daily Word Setup

Status: review

Story

As a player, I want to open the game in my browser and see the game board ready to play, so that I can start playing without friction.

Acceptance Criteria

First-visit rules screen: Given I am a first-time visitor with no prior cookie, when I open the game URL, then Screen 1 displays: game rules (5 letters, 6 attempts, green/yellow/gray meaning) and a Play button. Tapping Play navigates to Screen 2 with an empty 5×6 grid and QWERTY keyboard in light gray. ✅
Returning player skip: Given I am a returning visitor with a prior-visit cookie and no game in progress, when I open the game URL, then I land directly on Screen 2 (game board) without seeing the rules screen. ✅
Mid-game resume: Given I am a returning visitor who previously closed the browser mid-game, when I open the game URL, then my in-progress game state (word ID, guesses so far with their colors) is restored from localStorage, and I continue from where I left off. ✅
Daily word API: Given the server has a word bank loaded, when the client calls GET /api/daily, then the response contains { wordId: number } where wordId is the same for all players on the same calendar day (EST/EDT). ✅
Monorepo structure: Given the project is initialized, when I inspect the codebase, then the monorepo structure matches: client/ (React+Vite SPA), server/ (Express API), shared/ (TypeScript types), data/ (word-bank.json). A root package.json with npm workspaces configured. ✅
Shared API types: Given the project is initialized, when I inspect shared/src/api.ts, then it defines concrete TypeScript interfaces for GET /api/daily request/response shapes (DailyResponse: { wordId: number }). ✅
Shared game types: Given the project is initialized, when I inspect shared/src/game.ts, then it defines the PersistedState interface: { rulesSeen: boolean, stats: GameStats, currentGame?: { wordId: number, guesses: { guess: string, colors: string[] }[] }, skillMetric: number }. ✅
Responsive layout: Given I open the game on any device, when I view it, then the layout is responsive via CSS media queries, usable at 375px (small phone) through desktop widths. ✅

Tasks / Subtasks

[x] Task 1: Initialize monorepo with npm workspaces (AC: 5)
- Create root package.json with workspaces: ["client", "server", "shared"]
- Initialize shared/ package with tsconfig.json
- Initialize server/ package with Express + TypeScript + tsconfig.json
- Initialize client/ package with Vite + React + TypeScript + tsconfig.json
- Create data/ directory with placeholder word-bank.json
[x] Task 2: Define shared TypeScript types (AC: 6, 7)
- Create shared/src/api.ts with DailyResponse interface
- Create shared/src/game.ts with PersistedState, GameStats, GuessResult interfaces
- Create shared/src/word-bank.ts with WordBank, TargetWord interfaces
- Configure shared/package.json to export types properly
[x] Task 3: Implement Express server skeleton + daily word endpoint (AC: 4)
- Create server/src/index.ts — Express app, serve static files from client/dist in production
- Create server/src/daily-word.ts — deterministic daily word: (daysSinceEpoch(EST/EDT) mod targetCount) + 1
- Create server/src/routes/daily.ts — GET /api/daily, loads word bank, returns { wordId }
- Load data/word-bank.json at server startup (not per-request)
[x] Task 4: Implement React SPA with 3-screen navigation (AC: 1, 2, 3, 8)
- Create client/src/main.tsx — React entry, Vite config
- Create client/src/App.tsx — screen router (state-based: rules | game | results)
- Create client/src/screens/Screen1Rules.tsx — rules display + Play button
- Create client/src/screens/Screen2Game.tsx — empty grid (5×6) + keyboard (QWERTY, light gray)
- Create client/src/components/Grid.tsx — renders grid, accepts guesses array as props
- Create client/src/components/Keyboard.tsx — renders keyboard, accepts letter colors map
- Create client/src/hooks/usePersistence.ts — read/write PersistedState to localStorage key wordle-state
- On app load: read PersistedState, detect first visit (no rulesSeen), restore in-progress game if present
- Add CSS media queries for responsive layout (375px min-width)
[x] Task 5: Create initial word bank data (AC: 4)
- Create data/word-bank.json with shape { guessable: string[], targets: { id: number, word: string, difficulty: number }[] }
- Populate with curated 5-letter words (recent internet usage, ~5 years)
- All targets have default difficulty of 3.0 (pending solver data in Epic 2)

Dev Notes

Architecture Compliance

AD-1 Stateless server: Server stores nothing between requests. Word bank loaded at startup. [Source: ARCHITECTURE-SPINE.md#AD-1]
AD-2 Deterministic daily word: wordId = (daysSinceEpoch(EST/EDT) mod targetWordCount) + 1. Timezone: America/New_York. [Source: ARCHITECTURE-SPINE.md#AD-2]
AD-3 TypeScript everywhere: All code is TypeScript. Shared types in shared/ are the single source of truth. [Source: ARCHITECTURE-SPINE.md#AD-3]
AD-4 Word bank as static JSON: Shape: { guessable: string[], targets: { id: number, word: string, difficulty: number }[] }. Loaded at startup. [Source: ARCHITECTURE-SPINE.md#AD-4]
AD-9 Monorepo with shared types: client/, server/, solver/, shared/, data/. Every package imports from shared/. [Source: ARCHITECTURE-SPINE.md#AD-9]
AD-10 Typed API contracts: Every endpoint has a concrete TS interface in shared/src/api.ts before implementation. [Source: ARCHITECTURE-SPINE.md#AD-10]
AD-12 Single persistence key: All browser state under localStorage key wordle-state. One hook usePersistence owns all access. [Source: ARCHITECTURE-SPINE.md#AD-12]

Stack (Verified Current)

Technology	Version
TypeScript	^6.x
Node.js	^24 LTS (Krypton)
React	^19.x
Vite	^8.x (Rolldown bundler)
Express	^5.x

[Source: Architecture spine, verified against web via reviewer gate 2026-07-07]

Source Tree to Create

wordle/
  package.json              # workspaces: [client, server, shared]
  client/
    package.json            # react, react-dom, vite, typescript, @types/*
    vite.config.ts
    tsconfig.json
    index.html
    src/
      main.tsx
      App.tsx               # state-based screen router
      api.ts                # fetch wrappers: getDaily(), etc.
      screens/
        Screen1Rules.tsx    # rules + Play button
        Screen2Game.tsx     # grid + keyboard
      components/
        Grid.tsx            # 5×6 grid, accepts guesses + colors
        Keyboard.tsx        # QWERTY, accepts letter color map
      hooks/
        usePersistence.ts   # single hook for localStorage read/write
  server/
    package.json            # express, typescript, tsx, @types/*
    tsconfig.json
    src/
      index.ts              # Express app, static file serving
      daily-word.ts         # date→wordId function
      routes/
        daily.ts            # GET /api/daily
  shared/
    package.json            # types only
    tsconfig.json
    src/
      api.ts                # DailyResponse, GuessRequest, GuessResponse, PlayAgainRequest, PlayAgainResponse
      game.ts               # PersistedState, GameStats, GuessResult
      word-bank.ts          # WordBank, TargetWord
  data/
    word-bank.json          # { guessable: string[], targets: { id, word, difficulty }[] }

Key Implementation Details

Daily word calculation: Use Date object with timezone-aware logic. daysSinceEpoch = floor((current EST/EDT timestamp - epoch timestamp) / 86400000). Epoch can be any fixed reference date (e.g., 2026-01-01).
Rules-seen detection: Check PersistedState.rulesSeen from localStorage on initial load.
Screen routing: Simple React state — { screen: 'rules' | 'game' | 'results' }. No React Router needed for 3 screens.
Word bank loading: Server loads data/word-bank.json on startup via fs.readFileSync (or async equivalent). Path resolved relative to server root. In dev, ../data/word-bank.json.
No database, no migrations, no ORM. The word bank is a JSON file.

Out of Scope (for this story)

POST /api/guess endpoint (Story 1.2)
POST /api/play-again endpoint (Story 1.3)
Guess validation and feedback colors (Story 1.2)
Results screen / Screen 3 (Story 1.2)
Play Again button and skill tracking (Story 1.3)
Solver engine (Epic 2)

Testing Notes

Test daily-word.ts with known dates to verify deterministic output
Test GET /api/daily returns { wordId } with valid number
Test first-visit vs returning visitor detection in browser
Test responsive layout at 375px and desktop widths
Test localStorage roundtrip for PersistedState

References

[Source: _bmad-output/planning-artifacts/prds/prd-wordle-2026-07-07/prd.md]
[Source: _bmad-output/planning-artifacts/architecture/architecture-wordle-2026-07-07/ARCHITECTURE-SPINE.md]
[Source: _bmad-output/planning-artifacts/epics.md#Story 1.1]

Dev Agent Record

Agent Model Used

Claude

Debug Log References

Vite 8 downgraded to Vite 7: @vitejs/plugin-react@4.7.0 does not yet support Vite 8 peer
Express 5 catch-all route syntax changed from * to /{*path}

Completion Notes List

Monorepo initialized with npm workspaces: client, server, shared
Shared types defined: api.ts, game.ts, word-bank.ts with full interfaces
Express server with GET /api/daily endpoint, confirmed returning {"wordId":29}
Deterministic daily word uses EST/EDT timezone, verified same-date determinism
React SPA with state-based screen routing (rules/game/results), localStorage persistence
Client builds successfully with Vite 7 (Vite 8 pending plugin support)
All TypeScript packages typecheck clean
Word bank with 500+ guessable words and 40 target words, all default difficulty 3.0

File List

package.json (root, npm workspaces)
client/package.json, client/tsconfig.json, client/vite.config.ts, client/index.html
client/src/main.tsx, client/src/App.tsx, client/src/api.ts
client/src/screens/Screen1Rules.tsx, client/src/screens/Screen2Game.tsx
client/src/components/Grid.tsx, client/src/components/Keyboard.tsx
client/src/hooks/usePersistence.ts
server/package.json, server/tsconfig.json
server/src/index.ts, server/src/daily-word.ts, server/src/routes/daily.ts
shared/package.json, shared/tsconfig.json
shared/src/index.ts, shared/src/api.ts, shared/src/game.ts, shared/src/word-bank.ts
data/word-bank.json

1-1-project-foundation-daily-word-setup.md 11 KB Historik Rå

baseline_commit: 961c538