briangershon/planning-poker

Planning Poker built with Cloudflare Workers, Workers KV, Durable Objects, Websockets, and Cloudflare Pages. Also React, Redux Toolkit, TypeScript and Snowpack.

planning-poker

About

This game began as an entry in the Cloudflare Developer Challenge. See Changelog for v1.0.0.

Websocket support was added in v2.0.0.

The Cloudflare Developer Challenge is an event where developers are challenged to build an application using at least two of the products from the Cloudflare developer platform.

This project uses Cloudflare Workers, Workers KV, Durable Objects, Websockets and Cloudflare Pages. Also React, Redux Toolkit, TypeScript and Snowpack.

Cloudflare Durable Objects was ideal for maintaining persistent state for each game and its players, as well as being the central point for consolidating Websocket requests coming in from the network edge.

Screenshot

What's new?

See Changelog.

Github publishing instructions

• Create PR.
• Update changelog in the feature branch. Remember to add link at the bottom too. Commit and push.
• Merge PR.
• Bring down main branch.
• Tag it. For example git tag -a v2.0.0 -m "Add full websocket support"
• Push tag. For example git push origin v2.0.0

Run application locally

# setup nvm to manage Node.js versions

# in on terminal window run the backend
cd workers
nvm use       # miniflare needs Node > 12.x

# create and add development env SECRETS
cp .env.TEMPLATE .env.local
# edit .env.local
GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
GITHUB_CLIENT_SUCCESS_URL to http://localhost:8080


npm run dev   # uses miniflare instead of `wrangler dev`
# api is running at http://localhost:8787/api

# in second terminal window run the frontend
cd frontend
nvm use
npm install
npm start
# visit http://localhost:8080/

Run front-end tests

cd frontend
npm test

Deploy / Publish

Frontend

Setup Cloudflare Pages for PRODUCTION:

• Build command: npm run build:prod
• Build output directory: /build
• Root directory: /frontend

To deploy, push commits to this github repo.

Backend / Cloudflare worker

# setup Github oAuth secrets for production via wrangler
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put GITHUB_CLIENT_SUCCESS_URL to https://planningpoker.games

cd workers
nvm use
npm i @cloudflare/wrangler -g
wrangler publish

What is the game architecture?

Scope:

• A game has an ID, a status, a story sentence, and array of users and their card votes.
• No concept of game ownership/admin. Anyone can join and do anything in a game if they have the ID.
• Real-time updates via websockets

Workflow:

• Logged-in user creates game
  • create unique gameId to be used in both route and in Durable Object ID
  • persist gameId by user -- key: userId:gameId with value of createDate so we can delete games later.
• Visit any valid game route to participate in game. (Participant needs to be logged in)
• Users can cast votes, change story sentence, flip cards
• Poll for updates
• Only creator of game can delete it, albeit delete button shows up for all users.

How is this project organized?

• /frontend for static React site.

  • ./src/containers are components that pull in data from websockets, redux, api calls.
  • ./src/components should be presentation-only React components.
  • ./src/lib code modules that don't have a UI

• /workers for back-end Cloudflare code.

SVG Assets

• T-shirt SVG from https://svgsilh.com/image/34481.html
• Link icon from https://icons.getbootstrap.com

FAQs

When running locally, I see a "TypeError"

When running locally, if you see TypeError and The first argument must be of type string or an instance of Buffer. Received an instance of Uint8Array you're using an old version of Node.js. Run nvm use to get the latest version.

planning-poker's Issues

Add Contributor guidelines

If game hasn't started yet, player should not be able to vote yet.

Add walk-through / documentation

Remove demo for now; add latest t-shirt screenshots

When game ends, display calculated winning vote.

When game ends, it displays all the votes and team can decide what final answer is if they don't match. This feature is to calculate the "best" vote based on some algorithm, such as most votes or an average.

Mobile bugs

• Scrolling overflow pages go behind main menu
• Need to scroll horizontally

The second player joins game in two different browsers. If they voted, UI looks ok. If they haven't voted, they appear twice.

Issue: If same user joins game in another tab/window, if they've voted, UI looks ok.

• If they haven't voted, they appear twice.
• Also, name is being used for React <li> key, so generates a duplicate key error.

Update worker to use `blockConcurrencyWhile()` initialize method when Miniflare supports it.

Add ability for players to set examples of each t-shirt size in the game. e.g. `small` is roughly 1-day of work, `medium` is roughly 2 days of work, etc

Return `story` text in `/api/me` to display on Home page for list of active games (instead of a uuid)

Upgrade to React Router 6.x -- https://reactrouter.com/docs/en/v6/upgrading/v5

Demo

Ability to demo site without needing multiple github accounts.

Possible scenarios:

• Show a walk through (screenshots or video) of the site on the Home Page.
• Feature to add a rando user (that just votes as ? to show how it works) giving an extra user to try things out.

Add websockets to handle story updates and player updates

• Get websockets working on DEV env
• Ensure websockets working in production
• Add authentication (prevent ws connection if user not authenticated)
• Refactor auth logic to be used by HTTP and Web Sockets
• Add player voting logic
• Add story update logic
• Track all socket connections in Durable Object and broadcast message updates (votes, story). Remove polling logic.
• Remove http-based updates
• Retrieve full state of game when first loading (via websocket instead of http route)

Spruce up UI. Swap card graphics for t-shirts.

Focus on Game Play

• In prep, move game UI representational elements out of <PlayGame /> and into separate components.
• Formally start game with those that are in the lobby. Add state management. If people join during game, they won't be included. States include: lobby, in-progress, complete. To move from lobby, there need to be players and a story.
• Show user's presence before game starts -- should be in real time -- see people come/go
• Bug: When other plays first join game, they don't see initial people in game. Presence fixes should fix.
• Can't start game until there are at least two players
• Hide cards until all players have voted.
• Show green check on hidden cards when someone has voted so you can visually see who still has to vote.
• Automatically end game when all voters are in
• Ability to manually stop a game and flip cards
• When deleting game, send websocket event so other clients refresh
• update changelog

Fancy story edit: Click on text and edit in place. Save on onBlur. New React component.

Finishing touches

• logo
• favicon
• github oauth logo
• home page meta data

Move delete button to game list page (since for game owners only) -- and simplifies the game page.

Implementation advice:

I recommend initializing websockets on the home page (which lists all the games the user created) and using the websocket call to delete the project. This will then notify other clients if they happen to have the project open when it's deleted. Remember to close the connection when user leaves home page.