A full-stack implementation of the classic Codebreaker (Mastermind) game, with a primary focus on a vanilla HTML/CSS/JavaScript front-end paired with a lightweight .NET backend.
The Codebreaker game challenges the player to guess a secret sequence of colored pegs within a limited number of moves. After each guess the game responds with feedback indicating how many pegs are the correct color in the correct position and how many are the correct color but in the wrong position.
This repository showcases how a modern, framework-free browser front-end can be built with Web Components, the Fetch API, and OpenTelemetry — and how it integrates with a .NET 10 backend orchestrated by .NET Aspire.
src/Codebreaker/
├── Codebreaker.Frontend/ # Vanilla JS front-end (Vite)
│ ├── index.html # Application shell
│ ├── main.js # Game logic & orchestration
│ ├── style.css # Stylesheet
│ ├── telemetry.js # OpenTelemetry (traces, metrics, logs)
│ ├── vite.config.js # Vite config + Aspire service-discovery proxy
│ ├── components/
│ │ ├── color-peg.js # <color-peg> Web Component
│ │ ├── color-selector.js # <color-selector> Web Component
│ │ ├── feedback-peg.js # <feedback-peg> Web Component
│ │ └── game-row.js # <game-row> Web Component
│ └── services/
│ └── gameService.js # REST client for the Games API
├── Codebreaker.Frontend.Tests/ # Front-end tests
├── Codebreaker.GameAPIs/ # ASP.NET Core minimal API (Games API)
├── CodeBreaker.Bot/ # Automated bot that plays the game via the API
├── Codebreaker.Backend.AppHost/ # .NET Aspire AppHost (orchestration)
└── Codebreaker.Backend.ServiceDefaults/ # Shared Aspire service defaults
The front-end lives in Codebreaker.Frontend and is intentionally built without any UI framework — no React, Vue, or Angular. Instead it uses:
| Technology | Purpose |
|---|---|
Web Components (HTMLElement + Shadow DOM) |
Encapsulated, reusable UI elements (<color-peg>, <game-row>, <feedback-peg>, <color-selector>) |
| ES Modules | Native browser module system; bundled with Vite |
| Fetch API | All communication with the Games API via GameService |
| Drag & Drop | Native HTML drag-and-drop for placing pegs |
| OpenTelemetry JS SDK | Browser-side distributed tracing, metrics, and logging, exported via OTLP/HTTP |
| Vite | Dev server with HMR and production build |
cd src/Codebreaker/Codebreaker.Frontend
npm install
npm run devThe Vite dev server proxies /api requests to the Games API (default: https://localhost:9401).
telemetry.js configures the full OpenTelemetry JS SDK:
- Traces — spans around game actions (start game, submit move) using a custom tracer.
- Metrics — counters for games started/won/lost, moves submitted, errors; a histogram for move latency.
- Logs — structured log records emitted alongside spans.
When running under .NET Aspire, the OTLP endpoint and service name are injected automatically via environment variables and forwarded to the browser through a Vite proxy.
The backend included here is a slimmed-down version of the full backend, sufficient to run and develop the front-end locally. It consists of:
Codebreaker.GameAPIs— ASP.NET Core Minimal API (v3) for creating games and submitting moves. Uses an in-memory repository so no database setup is required.CodeBreaker.Bot— An ASP.NET Core service that exposes endpoints to trigger an automated bot player, useful for smoke-testing the API.Codebreaker.Backend.AppHost— Aspire AppHost that wires up the Games API, Bot, and Frontend together with service discovery and OpenTelemetry.Codebreaker.Backend.ServiceDefaults— Shared resilience, health-check, and observability defaults for all backend services.
Note: The full-featured backend (with Azure services, SQL/CosmosDB persistence, live game hub, and more) is maintained in a separate repository: CodebreakerApp/Codebreaker.Backend. This repo's backend will eventually be replaced by a direct reference to that repository.
cd src/Codebreaker
aspire runThe Aspire dashboard (typically at https://localhost:15888) shows all services, logs, traces, and metrics in one place.
| Tool | Version |
|---|---|
| .NET SDK | 10.0 or later |
| Node.js | 20 or later |
| npm | 10 or later |
| Resource | Description |
|---|---|
| CodebreakerApp/Codebreaker.Backend | Full-featured backend — the source this repo's backend is derived from |
| CodebreakerApp Organization | All Codebreaker-related repositories |
| PacktPublishing/Pragmatic-Microservices-with-CSharp-and-Azure | Book repository — covers multiple iterations of the Codebreaker backend, from a simple monolith to a cloud-native microservices architecture on Azure, using .NET Aspire, gRPC, SignalR, and more |
The book "Pragmatic Microservices with C# and Azure" (Packt) walks through the evolution of the backend step by step and is the ideal companion for understanding the architectural decisions behind this project.
See LICENSE for details.