# zwkrl/heritage-plate architecture

> Architecture diagram of the GitHub repository zwkrl/heritage-plate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zwkrl/heritage-plate
- Repository: https://github.com/zwkrl/heritage-plate

## Overview

IDEA2 Heritage Plate is a browser-based heritage cooking game. The player starts a session and follows dish-specific preparation, cooking, and serving challenges using keyboard inputs; the game tracks progress and score, then presents the result through canvas visuals and audio cues. Dish recipes and ingredient definitions drive the challenges, while the engine coordinates input, game state, rendering, and leaderboard persistence. An optional ESP32 button setup translates physical presses into keyboard events. The engine excerpt is partial, so stage links summarize documented game behavior rather than claiming every internal transition was inspected.

Main entry points: [`vite-app/src/game/engine.js`](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js) (Game engine), [`vite-app/src/main.js`](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/main.js) (Browser bootstrap), [`vite-app/src/game/render.js`](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/render.js) (Canvas rendering), [`arduino/arcade_buttons_arduino.ino`](https://github.com/zwkrl/heritage-plate/blob/main/arduino/arcade_buttons_arduino.ino) (Button firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Browser entry"]
  node_app["Browser bootstrap<br/>[main.js]"]
  node_browser["Browser canvas and HUD<br/>[index.html]"]
end

subgraph group_gameplay["Cooking gameplay"]
  node_engine["Game engine<br/>[engine.js]"]
  node_recipes["Dish recipes<br/>[data.js]"]
  node_prep["Ingredient preparation<br/>[engine.js]"]
  node_cook["Cooking challenges<br/>[engine.js]"]
  node_plate["Plating and serving<br/>[engine.js]"]
  node_score["Score and combos<br/>[engine.js]"]
end

subgraph group_presentation["Game presentation"]
  node_canvas["Canvas rendering<br/>[render.js]"]
  node_art["Game assets"]
  node_audio["Sound cues<br/>[audio.js]"]
end

subgraph group_controls["Input and state"]
  node_leaderboard[("Local leaderboard<br/>[engine.js]")]
  node_firmware["Button firmware"]
  node_bridge["Serial key bridge<br/>[buttons.py]"]
end

node_player(("Player"))
node_physical(("Physical buttons"))
node_keyboard(("Keyboard events"))

node_player -->|"starts game"| node_app
node_app -->|"binds UI"| node_browser
node_app -->|"creates game"| node_engine
node_engine -->|"reads recipes"| node_recipes
node_engine -->|"runs stage"| node_prep
node_engine -->|"runs stage"| node_cook
node_engine -->|"runs stage"| node_plate
node_engine -->|"updates score"| node_score
node_engine -->|"draws state"| node_canvas
node_engine -->|"plays cues"| node_audio
node_engine -->|"reads and writes"| node_leaderboard
node_canvas -->|"loads images"| node_art
node_player -->|"presses keys"| node_keyboard
node_keyboard -->|"dispatches events"| node_engine
node_physical -.->|"presses buttons"| node_firmware
node_firmware -.->|"sends serial"| node_bridge
node_bridge -.->|"emits key events"| node_keyboard

click node_app "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/main.js"
click node_engine "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_recipes "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/data.js"
click node_prep "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_cook "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_plate "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_score "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_canvas "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/render.js"
click node_art "https://github.com/zwkrl/heritage-plate/tree/main/vite-app/public/assets"
click node_audio "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/audio.js"
click node_browser "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/index.html"
click node_leaderboard "https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js"
click node_firmware "https://github.com/zwkrl/heritage-plate/blob/main/arduino/arcade_buttons_arduino.ino"
click node_bridge "https://github.com/zwkrl/heritage-plate/blob/main/arduino/buttons.py"

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_app,node_browser toneBlue
class node_engine,node_recipes,node_prep,node_cook,node_plate,node_score toneAmber
class node_canvas,node_art,node_audio toneMint
class node_leaderboard,node_firmware,node_bridge toneRose
class node_player,node_physical,node_keyboard toneIndigo
```

## Components

### Browser entry

- [Browser bootstrap](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/main.js): `vite-app/src/main.js`
- [Browser canvas and HUD](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/index.html): `vite-app/index.html`

### Cooking gameplay

- [Game engine](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`
- [Dish recipes](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/data.js): `vite-app/src/game/data.js`
- [Ingredient preparation](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`
- [Cooking challenges](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`
- [Plating and serving](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`
- [Score and combos](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`

### Game presentation

- [Canvas rendering](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/render.js): `vite-app/src/game/render.js`
- [Game assets](https://github.com/zwkrl/heritage-plate/tree/main/vite-app/public/assets): `vite-app/public/assets`
- [Sound cues](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/audio.js): `vite-app/src/game/audio.js`

### Input and state

- [Local leaderboard](https://github.com/zwkrl/heritage-plate/blob/main/vite-app/src/game/engine.js): `vite-app/src/game/engine.js`
- [Button firmware](https://github.com/zwkrl/heritage-plate/blob/main/arduino/arcade_buttons_arduino.ino): `arduino/arcade_buttons_arduino.ino`
- [Serial key bridge](https://github.com/zwkrl/heritage-plate/blob/main/arduino/buttons.py): `arduino/buttons.py`

### Other components

- **Player**
- **Physical buttons**
- **Keyboard events**

## Connections

- Player → Browser bootstrap: starts game
- Browser bootstrap → Browser canvas and HUD: binds UI
- Browser bootstrap → Game engine: creates game
- Game engine → Dish recipes: reads recipes
- Game engine → Ingredient preparation: runs stage
- Game engine → Cooking challenges: runs stage
- Game engine → Plating and serving: runs stage
- Game engine → Score and combos: updates score
- Game engine → Canvas rendering: draws state
- Game engine → Sound cues: plays cues
- Game engine → Local leaderboard: reads and writes
- Canvas rendering → Game assets: loads images
- Player → Keyboard events: presses keys
- Keyboard events → Game engine: dispatches events
- Physical buttons → Button firmware: presses buttons
- Button firmware → Serial key bridge: sends serial
- Serial key bridge → Keyboard events: emits key events