Skip to main content

Architecture Overview

DoubleCube.gg is a multi-project .NET solution with a React frontend. This page provides a high-level overview of the system architecture.

System Diagram​

┌─────────────────────────────────────────────────────────────────┐
│ Frontend Clients (Browser) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tab 1 │ │ Tab 2 │ │ Tab N │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
SignalR WebSocket + REST API
│
┌─────────────────────────────────────────────────────────────────┐
│ Backgammon.Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ GameHub │ │ REST API │ │ Services │ │
│ │ (SignalR) │ │ Endpoints │ │ Layer │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ Backgammon.Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ GameEngine │ │ Board │ │ Match │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ Data Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ DynamoDB │ │ HybridCache │ │ Redis │ │
│ │ (Storage) │ │ (Caching) │ │ (Backplane) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Project Dependencies​

Backgammon.AppHost (Aspire)
└── Backgammon.Server
├── Backgammon.Core
├── Backgammon.AI
├── Backgammon.Analysis
└── Backgammon.Plugins

Backgammon.WebClient (React)
└── TypeScript client generated from IGameHub/IGameHubClient

Key Design Principles​

1. Server-Authoritative Logic​

All game rules are enforced on the server in Backgammon.Core. The client cannot cheat because:

  • Move validation happens server-side
  • Dice rolls are generated on the server
  • Game state is stored in the server's GameSession

2. Pure Domain Logic​

Backgammon.Core has zero dependencies. It contains only:

  • Game rules (movement, hitting, bearing off)
  • Board representation
  • Match scoring
  • Doubling cube logic

This makes the core logic easy to test and reuse.

3. Real-Time Communication​

SignalR provides bidirectional WebSocket communication:

  • Client → Server: invoke() for actions (roll dice, make move)
  • Server → Client: Events pushed to all connected tabs

4. Multi-Tab Support​

A single player can have multiple browser tabs open:

  • Each tab has its own connection ID
  • Player tracked by HashSet<string> of connection IDs
  • All tabs receive game updates
  • Any tab can make moves

5. Single-Table DynamoDB Design​

All entities stored in one DynamoDB table with composite keys:

  • Efficient queries via GSIs
  • Cost-effective (pay-per-request)
  • Flexible schema for different entity types

Communication Patterns​

Game Actions​

  1. Client calls connection.invoke('MakeMove', from, to)
  2. Server validates move in GameEngine
  3. Server broadcasts GameUpdate to all players' connections
  4. All tabs update their UI

Authentication​

  1. JWT token stored in localStorage
  2. Token sent via query string for SignalR: /gamehub?access_token=xxx
  3. Anonymous users created automatically on first visit

Learn More​