How vinson1906/puzzle-game works
Purpose and Entry Points
Puzzle Workshop is a Next.js 14 App Router application for creating and solving client-side photo sliding puzzles. The root route renders the game experience through app/page.tsx; shared document structure and global styling originate in app/layout.tsx and app/globals.css.
Application Shell
The App Router provides the runtime boundary between page rendering and server endpoints. app/page.tsx composes the puzzle UI, while app/layout.tsx establishes the application-wide layout. Global visual tokens and baseline CSS belong in app/globals.css.
Puzzle Game Engine
components/PuzzleGame.tsx is the primary feature component and owns both UI state and gameplay control flow:
• Receives an uploaded or dropped image in the browser.
• Uses an off-screen canvas to slice it into gridSize × gridSize image tiles.
• Shuffles tiles with Fisher–Yates, avoiding an initially solved board.
• Tracks selected tiles, swaps, move count, timer state, and solved status.
• Detects completion by comparing each tile’s current position to its original index.
This is browser-dependent logic because it relies on file input, drag/drop, image decoding, and canvas APIs.
Puzzle Data Flow
The dominant client flow is: user image input → canvas-generated tile assets → shuffled board state → click-driven swaps → solved-board detection. Tile identity must remain stable independently of board position so correctness can be checked after each move. Grid-size selection changes the number of generated pieces and triggers a new board-generation cycle.
Scores API and Persistence Boundary
A server route exists at app/api/scores/route.ts, defining the /api/scores boundary for score-oriented reads and/or writes. Persistence connectivity is isolated in lib/dBConnections.ts, and the score record shape/model is defined in lib/models/Score.ts. This separation keeps browser gameplay state distinct from database access and allows the puzzle component or page layer to submit completed-game results through HTTP rather than directly accessing storage.
Runtime and Infrastructure
The project runs on Next.js with TypeScript, configured by next.config.js and package metadata in package.json. Client rendering handles the interactive puzzle; Next.js route handlers provide server-side API execution. The presence of lib/dBConnections.ts and lib/models/Score.ts indicates a database-backed score subsystem, though the specific database service is not established by the supplied tree.
Static Assets
Publicly served resources are located under public/, including public/accets. User-provided puzzle images are processed in-memory in the browser rather than requiring a static-asset upload pipeline.
Main entry points: next.config.js Next.js runtime · PuzzleGame.tsx Puzzle game · route.ts Scores API · page.tsx Puzzle page
Components 14
Next.js App
- Root layout
app/layout.tsx - Global styles · Defines visual tokens and baseline styling.
app/globals.css - Puzzle page
app/page.tsx - Public assets · Includes public/accets.
- Next.js runtime · Serves App Router pages and server route handlers.
next.config.js - Package metadata · Defines the Next.js and TypeScript project dependencies.
package.json
Client Puzzle
- Puzzle game · Owns interactive gameplay state and control flow.
components/PuzzleGame.tsx - Image input
- Tile generation · Decodes and slices the image into grid tiles.
- Shuffled board · Keeps stable tile identities, positions, moves, timer, and solved state.
Scores Backend
- Scores API · HTTP boundary for score reads and writes.
app/api/scores/route.ts - Database connection · Database vendor is unspecified.
lib/dBConnections.ts - Score model
lib/models/Score.ts
Other components
- Puzzle player
Connections 15
- Puzzle player → Puzzle page: opens
- Next.js runtime → Root layout: renders
- Next.js runtime → Puzzle page: renders
- Root layout → Global styles: applies
- Puzzle page → Puzzle game: composes
- Puzzle game → Image input: accepts
- Image input → Tile generation: image data
- Tile generation → Shuffled board: tile assets
- Shuffled board → Puzzle game: swaps and completion
- Puzzle game → Scores API: submits completed score
- Next.js runtime → Scores API: executes
- Scores API → Database connection: uses
- Scores API → Score model: reads and writes
- Package metadata → Next.js runtime: declares
- Public assets → Puzzle page: served to