Architecture Overview

High-level architecture and technical stack of BeeHex Progressive Web App

Technology Stack

BeeHex is built as a modern Progressive Web App using the following core technologies:

Frontend Framework

Next.js 14.2 with React 18 for server-side rendering and routing

Language

TypeScript 5 for type-safe development across the entire codebase

Styling

Styled Components 6.1 for component-scoped CSS-in-JS styling

Real-time Communication

Socket.io Client 4.7 for WebSocket-based multiplayer gameplay

System Architecture

BeeHex follows a client-heavy architecture where complex game logic and AI computations run directly in the browser.

Core Components

GameInstance

The central game state manager located in src/app/hex/[gameId]/GameInstance.ts.

Key Responsibilities:

• Maintains the game grid as a 2D array: Array<Array<number>>
• Tracks player IDs (first_player_id, second_player_id)
• Manages turn state and validates moves
• Provides methods for state updates and player queries

class GameInstance {
  private grid_array: Array<Array<number>>;
  private turn: number;
  
  isValidMove(i: number, j: number): boolean {
    return this.grid_array[i][j] === 0;
  }
  
  getCurrentPlayer(): UserId {
    return this.turn % 2 === 0 
      ? this.second_player_id 
      : this.first_player_id;
  }
}

WebSocket Handler

Manages real-time communication with the game server via WebSocket protocol.

Location: src/app/game_mode/WebsocketHandler.ts

Features:

• Bidirectional packet communication
• Callback-based event handling
• Automatic connection management
• JSON-based packet serialization

class WebsocketHandler {
  private socket: WebSocket;
  
  constructor(callbacks: WebsocketCallbacks) {
    this.socket = new WebSocket(`ws:/${HOST}:3002/`);
    this.socket.onmessage = (e) => {
      const packet = JSON.parse(e.data);
      this.handlePacket(packet);
    };
  }
}

AI Explorer

The game AI system that explores possible moves using minimax algorithm with Web Workers.

Location: src/app/hex/[gameId]/Algorithm.ts

Key Classes:

• Explorer: Manages the search tree and coordinates workers
• ScoredGameInstance: Game state with evaluation score
• Score: Represents position evaluation with win countdown

The AI explores 2 levels deep per worker iteration and uses a heuristic based on path cost and bridge counting.

Data Flow

Online Multiplayer Flow

1. Player initiates game search

   Client sends GAME_SEARCH packet with GameParameters (board size, ranked status)

2. Server matches players

   Server responds with GAME_FOUND packet containing game_id

3. Join game room

   Client sends JOIN_GAME packet and receives full Game object with initial state

4. Gameplay loop

   Players send PLAY_MOVE packets, server broadcasts MOVE_PLAYED to both clients

Offline Mode Flow

1. Local Game Creation: Creates GameInstance with LocalGameParameters
2. AI Move Request: Explorer spawns Web Workers to evaluate positions
3. Worker Exploration: Each worker explores 2 levels deep using basicHeuristic
4. Move Recommendation: Best moves returned with optimal continuation paths

Performance Optimizations

BeeHex implements several performance optimizations to handle complex game tree search:

Array Caching

The ArrayCache class (src/app/hex/[gameId]/ArrayCache.ts:1) reduces memory allocation during game tree exploration:

class ArrayCache {
  private cache: Map<ArrayHash, Array<number>>;
  
  getFromOne(array: Array<number>, index: number, value: number) {
    let hash = ArrayCache.hashArrayFromOne(array, index, value);
    if (this.cache.has(hash)) {
      return this.cache.get(hash)!; // Reuse cached array
    }
    // Create and cache new array
  }
}

Grid Hashing

Board positions are hashed to base-36 strings for efficient deduplication:

function hashGrid(grid: Array<Array<number>>): GridHash {
  let hash = 0n;
  let ii = 1n;
  for (let row of grid) {
    for (let cell of row) {
      hash += BigInt(cell) * ii;
      ii *= 3n; // Ternary encoding (0=empty, 1=red, 2=blue)
    }
  }
  return hash.toString(36);
}

Memory Management

Explored game states clear their grid arrays once children are created to conserve memory:

// From Algorithm.ts:198
this.grid = empty_array; // Clear grid after children explored

Type System

BeeHex uses comprehensive TypeScript interfaces defined in src/app/definitions.ts:

• Game Types: Game, GameParameters, GameStatus
• Network Packets: ClientBoundPacket, ServerBoundPacket enums and interfaces
• AI Types: RawScoredGameInstance, ExploreResult, Coordinate
• Identifiers: UserId, GameId, RoomId, GridHash

All packet types use discriminated unions with type field for type-safe message handling.

Directory Structure

src/app/
├── hex/[gameId]/           # Game page and core logic
│   ├── GameInstance.ts     # Game state management
│   ├── Algorithm.ts        # AI engine (Explorer, Score)
│   ├── AlgorithmWorker.ts  # Web Worker for parallel search
│   └── ArrayCache.ts       # Performance optimization
├── game_mode/
│   └── WebsocketHandler.ts # Multiplayer communication
└── definitions.ts          # Shared types and interfaces

Next Steps

Game Engine

Deep dive into AI algorithms and game state management

WebSocket Protocol

Complete packet specification and communication flow