Distributed Codenames

A multiplayer, realtime application based on the rules of the board game Codenames. The project aims to follow a microservice based architecture while maintaining vendor neutrality. It also makes use of cloud native technologies (see CNCF Landscape).

Contributing

This project is a way for me to experiment, evaluate, and demo new technologies. If you find a bug, spot an optimization, encounter a bad practice, or simply want to point out something unidiomatic, please open an issue before raising a pull request.

Required tools

Running inside a Development Container (see .devcontainer)

1. VSCode or the Dev Container CLI
2. Docker

Running natively

1. Docker
2. A local Kubernetes environment v1.27+ or v1.23+ with feature flag GRPCContainerProbe
   • (Recommended) Minikube
   • Kind
3. Helm
4. Skaffold
5. ko for building Go containers without docker
6. (Optional) Pack for Cloud Native Buildpacks
7. (Optional) Languages to run applications natively (see architecture table below)

Architecture

Service	Language / Framework	Notes
Games API	Go / gRPC	Handles game logic, stores state in Valkey and publishes updates to NATS
Games BFF	TypeScript / Express	ts-rest, Node.js, subscribes to NATS and streams game updates to players in real time with websockets
Games SPA	TypeScript / React	Game frontend build with Vite, Material UI, React Hook Form, axios, and hosted via NGINX
Lobbies API	C# / ASP.NET	Uses SignalR with a Valkey backplane to stream updates to the SPA
Lobbies SPA	TypeScript / Angular	Built with Angular Material and tailwindcss, allows players to select their team
Players API	Python / FastAPI	Handles player state with Valkey
Players SPA	TypeScript / React	Allows players to set and update their nickname, built with formik hosted via NGINX
Words API	Go / gRPC	Provides different word lists to vary games

Local development

Start minikube

minikube start --profile codenames
skaffold config set --global local-cluster true
eval $(minikube -p codenames docker-env)

Install Helm Dependencies

Current dependencies are:

1. Envoy Gateway
2. NATS
3. Valkey (Redis fork)

helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm repo update
helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm --version v1.0.1 -n envoy-gateway-system --create-namespace
helm install nats nats/nats
helm install games-db oci://registry-1.docker.io/bitnamicharts/valkey --set architecture=standalone
helm install lobbies-db oci://registry-1.docker.io/bitnamicharts/valkey --set architecture=standalone
helm install players-db oci://registry-1.docker.io/bitnamicharts/valkey --set architecture=standalone

Startup services

skaffold dev

Debugging nats

kubectl exec -n default -it my-nats-box -- /bin/sh -l
nats-sub <subject>