Architecture Overview

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
WebSocket Handler
AI Explorer

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;
  }
}

Manages real-time communication with the game server via WebSocket protocol.Location: src/app/game_mode/WebsocketHandler.tsFeatures:

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);
    };
  }
}

The game AI system that explores possible moves using minimax algorithm with Web Workers.Location: src/app/hex/[gameId]/Algorithm.tsKey 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

Player initiates game search

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

Server matches players

Server responds with GAME_FOUND packet containing game_id

Join game room

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

Gameplay loop

Players send PLAY_MOVE packets, server broadcasts MOVE_PLAYED to both clients

Offline Mode Flow

Local Game Creation: Creates GameInstance with LocalGameParameters
AI Move Request: Explorer spawns Web Workers to evaluate positions
Worker Exploration: Each worker explores 2 levels deep using basicHeuristic
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

Architecture

Development

Architecture Overview

Technology Stack

Frontend Framework

Language

Styling

Real-time Communication

System Architecture

Core Components

Data Flow

Online Multiplayer Flow

Offline Mode Flow

Performance Optimizations

Array Caching

Grid Hashing

Memory Management

Type System

Directory Structure

Next Steps

Game Engine

WebSocket Protocol

Build docs developers (and LLMs) love

Architecture

Development

Documentation Index

​Technology Stack

Frontend Framework

Language

Styling

Real-time Communication

​System Architecture

​Core Components

​Data Flow

​Online Multiplayer Flow

​Offline Mode Flow

​Performance Optimizations

​Array Caching

​Grid Hashing

​Memory Management

​Type System

​Directory Structure

​Next Steps

Game Engine

WebSocket Protocol

Build docs developers (and LLMs) love

Technology Stack

System Architecture

Core Components

Data Flow

Online Multiplayer Flow

Offline Mode Flow

Performance Optimizations

Array Caching

Grid Hashing

Memory Management

Type System

Directory Structure

Next Steps