# vinson1906/puzzle-game architecture

> Architecture diagram of the GitHub repository vinson1906/puzzle-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinson1906/puzzle-game
- Repository: https://github.com/vinson1906/puzzle-game

## Overview

#### 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`](https://github.com/vinson1906/puzzle-game/blob/main/next.config.js) (Next.js runtime), [`components/PuzzleGame.tsx`](https://github.com/vinson1906/puzzle-game/blob/main/components/PuzzleGame.tsx) (Puzzle game), [`app/api/scores/route.ts`](https://github.com/vinson1906/puzzle-game/blob/main/app/api/scores/route.ts) (Scores API), [`app/page.tsx`](https://github.com/vinson1906/puzzle-game/blob/main/app/page.tsx) (Puzzle page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js App"]
  node_layout["Root layout<br/>App Router layout<br/>[layout.tsx]"]
  node_globals["Global styles<br/>CSS<br/>[globals.css]"]
  node_page["Puzzle page<br/>App Router page<br/>[page.tsx]"]
  node_static_assets["Public assets<br/>static resources"]
  node_runtime{{"Next.js runtime<br/>framework runtime<br/>[next.config.js]"}}
  node_package["Package metadata<br/>dependencies<br/>[package.json]"]
end

subgraph group_game["Client Puzzle"]
  node_puzzle["Puzzle game<br/>client component<br/>[PuzzleGame.tsx]"]
  node_image_input["Image input"]
  node_tile_generation["Tile generation<br/>canvas pipeline"]
  node_board_state["Shuffled board<br/>client state"]
end

subgraph group_scores["Scores Backend"]
  node_scores_route["Scores API<br/>route handler<br/>[route.ts]"]
  node_db_connection[("Database connection<br/>persistence connector<br/>[dBConnections.ts]")]
  node_score_model["Score model<br/>record model<br/>[Score.ts]"]
end

node_user(("Puzzle player<br/>browser user"))

node_user -->|"opens"| node_page
node_runtime -->|"renders"| node_layout
node_runtime -->|"renders"| node_page
node_layout -->|"applies"| node_globals
node_page -->|"composes"| node_puzzle
node_puzzle -->|"accepts"| node_image_input
node_image_input -->|"image data"| node_tile_generation
node_tile_generation -->|"tile assets"| node_board_state
node_board_state -->|"swaps and completion"| node_puzzle
node_puzzle -.->|"submits completed score"| node_scores_route
node_runtime -->|"executes"| node_scores_route
node_scores_route -->|"uses"| node_db_connection
node_scores_route -->|"reads and writes"| node_score_model
node_package -->|"declares"| node_runtime
node_static_assets -.->|"served to"| node_page

click node_layout "https://github.com/vinson1906/puzzle-game/blob/main/app/layout.tsx"
click node_globals "https://github.com/vinson1906/puzzle-game/blob/main/app/globals.css"
click node_page "https://github.com/vinson1906/puzzle-game/blob/main/app/page.tsx"
click node_puzzle "https://github.com/vinson1906/puzzle-game/blob/main/components/PuzzleGame.tsx"
click node_scores_route "https://github.com/vinson1906/puzzle-game/blob/main/app/api/scores/route.ts"
click node_db_connection "https://github.com/vinson1906/puzzle-game/blob/main/lib/dBConnections.ts"
click node_score_model "https://github.com/vinson1906/puzzle-game/blob/main/lib/models/Score.ts"
click node_runtime "https://github.com/vinson1906/puzzle-game/blob/main/next.config.js"
click node_package "https://github.com/vinson1906/puzzle-game/blob/main/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_globals,node_page,node_static_assets,node_runtime,node_package toneBlue
class node_puzzle,node_image_input,node_tile_generation,node_board_state toneAmber
class node_scores_route,node_db_connection,node_score_model toneMint
class node_user toneNeutral
```

## Components

### Next.js App

- [Root layout](https://github.com/vinson1906/puzzle-game/blob/main/app/layout.tsx): App Router layout · `app/layout.tsx`
- [Global styles](https://github.com/vinson1906/puzzle-game/blob/main/app/globals.css): CSS · Defines visual tokens and baseline styling. · `app/globals.css`
- [Puzzle page](https://github.com/vinson1906/puzzle-game/blob/main/app/page.tsx): App Router page · `app/page.tsx`
- **Public assets**: static resources · Includes public/accets.
- [Next.js runtime](https://github.com/vinson1906/puzzle-game/blob/main/next.config.js): framework runtime · Serves App Router pages and server route handlers. · `next.config.js`
- [Package metadata](https://github.com/vinson1906/puzzle-game/blob/main/package.json): dependencies · Defines the Next.js and TypeScript project dependencies. · `package.json`

### Client Puzzle

- [Puzzle game](https://github.com/vinson1906/puzzle-game/blob/main/components/PuzzleGame.tsx): client component · Owns interactive gameplay state and control flow. · `components/PuzzleGame.tsx`
- **Image input**: browser file and drop APIs
- **Tile generation**: canvas pipeline · Decodes and slices the image into grid tiles.
- **Shuffled board**: client state · Keeps stable tile identities, positions, moves, timer, and solved state.

### Scores Backend

- [Scores API](https://github.com/vinson1906/puzzle-game/blob/main/app/api/scores/route.ts): route handler · HTTP boundary for score reads and writes. · `app/api/scores/route.ts`
- [Database connection](https://github.com/vinson1906/puzzle-game/blob/main/lib/dBConnections.ts): persistence connector · Database vendor is unspecified. · `lib/dBConnections.ts`
- [Score model](https://github.com/vinson1906/puzzle-game/blob/main/lib/models/Score.ts): record model · `lib/models/Score.ts`

### Other components

- **Puzzle player**: browser user

## Connections

- 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