From 6e10ab511fb922c47eb34c3e4621571cdf1ffdd4 Mon Sep 17 00:00:00 2001 From: Nick Carbone Date: Thu, 17 Oct 2024 08:38:50 -0400 Subject: [PATCH 1/4] update readme --- .github/workflows/ci.yml | 12 +- .github/workflows/stage.yml | 4 +- README.md | 128 +++++++++++++++- client/README.md | 1 - client/package.json | 2 - client/src/components/use-game-machine.ts | 2 +- client/src/services/api.high-score.ts | 2 +- client/tsconfig.app.json | 2 +- package.json | 23 ++- pnpm-lock.yaml | 174 +++++++++++----------- server/package.json | 1 - 11 files changed, 243 insertions(+), 108 deletions(-) delete mode 100644 client/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5571ff2..98cdecb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -28,7 +28,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -52,7 +52,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -76,7 +76,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -100,7 +100,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -134,7 +134,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -168,7 +168,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install diff --git a/.github/workflows/stage.yml b/.github/workflows/stage.yml index 9a0c5e5..746f5b3 100644 --- a/.github/workflows/stage.yml +++ b/.github/workflows/stage.yml @@ -46,7 +46,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install @@ -79,7 +79,7 @@ jobs: - name: ⎔ Setup node uses: actions/setup-node@v4 with: - node-version: 20.10.0 + node-version: 22.9.0 - name: 📥 Install deps run: pnpm install diff --git a/README.md b/README.md index ecad94b..db5ae78 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,118 @@ # Simon +This is a case study in application architecture for the classic memory game Simon. The game requires the user to play back a computer generated sequence of notes that increases in length each turn. + +Play now! https://simon.codenickycode.com + +## Architecture + ![architecture diagram](./docs/simon-arch.png) -# Debug +### Front End + +This application uses [React](https://react.dev) to separate data, logic, and visual elements into separate components. State is maintained via React hooks, and UI is rendered as html via jsx. Musical sequencing and synthesis is made possible by [Tone.js](https://tonejs.github.io/), an abstraction over the Web Audio API. It is deployed via [Cloudflare Pages](https://developers.cloudflare.com/pages/). + +#### [Root](./client/src/simon.tsx) + +The parent function that orchestrates all other components to fetch data, maintain state, and render UI. This is the root of our React application. + +#### [API](./client//src/services/api.high-score.ts) + +A service to retrieve and update the global high score from our back end API. This component stores the pending, success, and error states of all requests. + +#### [Game State](./client/src/components/use-game-machine.ts) + +A finite state machine that maintains the status of the game: New Game, Computer Turn, User Turn, Game Over. It uses the [state reducer pattern](https://kentcdodds.com/blog/the-state-reducer-pattern-with-react-hooks), accepting a single action to transition state and update the user's current score. + +#### [Pad Controller](./client/src/components/use-pad-controller.ts) + +A stateful hook that controls the "active" status of each pad and provides methods for accepting user and computer pad input. + +#### [Melody Player](./client/src/services/melody-player.ts) + +Preset melodies to play when entering the game over state. + +#### [Sequencer](./client/src/services/sequencer.ts) + +Builds a sequence of notes as the game progresses. These are the notes the user must repeat in order to continue playing. The sequencer plays tones using a synth and is observed by the pad controller to set the current playing pad as active. + +#### Synths + +These are `Tone.Synth` instances that receive input from the pad controller, melody player, and sequencer to emit tones to the audio device. See [Tone.js | Class Synth](https://tonejs.github.io/docs/15.0.4/classes/Synth.html) + +### Back End + +The back end is a simple [Hono](https://hono.dev/) REST API on [Cloudflare Workers](https://developers.cloudflare.com/workers/) and a [Cloudflare KV](https://developers.cloudflare.com/kv/) database. It exposes retrieving and updating a global high score. + +# Development + +## Getting Started + +### Pre-requisites -## Server starts on wrong port locally +1. [pnpm](https://pnpm.io/installation) v9 and above +2. [node](https://nodejs.org/en/download/package-manager/current) v22.9.0 and above + +### Installation + +1. Ensure you're using the correct version of Node: + + ```sh + nvm use 22.9.0 + ``` + +2. If necessary, install the correct version of pnpm: + + ```sh + npm i -g pnpm@9 + ``` + +3. Install dependencies + + ```sh + pnpm i + ``` + +4. Start local dev server + + ```sh + pnpm run dev + ``` + +### Deployment Configuration + +1. Follow instructions in [README.cloudflare](./README.cloudflare/README.cloudflare.md) + +2. Follow instructions in [README.sentry](./README.sentry/README.sentry.md) + +### Deploying a branch to stage + +1. Click the "Actions" tab +2. Select the "stage" workflow +3. Open the dropdown for "Run workflow" and select the branch you wish to deploy +4. Choose your deploy target (client, server, both) +5. Click "Run workflow" + +The client app will deploy to the preview url, and the server will deploy to your staging worker. + +## Scripts + +- `pnpm run dev`: Start the development server +- `pnpm run lint`: Run ESLint +- `pnpm run test`: Run unit tests with Vitest +- `pnpm run typecheck`: Run TypeScript type checking +- `pnpm run format`: Format code with Prettier +- `pnpm run e2e`: Run end-to-end tests with Playwright + +Some convenience scripts for shortcuts: + +- `pnpm run clean`: Execute a clean install of package dependencies +- `pnpm run client