# virgs/2048-ai architecture

> Architecture diagram of the GitHub repository virgs/2048-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virgs/2048-ai
- Repository: https://github.com/virgs/2048-ai

## Overview

##### Project Type and Purpose
- This is a front-end oriented game project that combines an interactive UI (built with React and TypeScript) with a game engine and an artificial intelligence (AI) agent.
- The AI uses a variation of Pure Monte Carlo Tree Search (MCTS) to make decisions for playing the 2048 game.
- The project also involves performance reporting and uses modern tooling (Vite, TypeScript) and component-based UI design.

##### File Structure
- Top-level directories include:
– “src”: Contains the application code (React components, AI modules, game engine logic, and assets).
– “docs”: Contains support files like WebWorker scripts that might be used for offloading computation-intensive tasks (e.g., running Monte Carlo simulations in a separate thread).
– “public”: Likely holds static assets and the HTML template for hosting the React app (e.g., index.html).
– “reports”: Contains JSON and JS files that aggregate data/results from the AI runs, indicating that performance/analytics is a key aspect.
- Within “src”:
– “components” holds the UI pieces (board, grid, score, game modals, etc.).
– “engine” holds the core game logic (board representation, movements, game rules, etc.).
– “ai” contains files dedicated to AI’s Monte Carlo simulation logic (e.g., MonteCarlo.ts, NextMoveAiWorker.ts, ReportGenerator.ts) and support code for using Web Workers.

##### README for Additional Insights
- The README gives a good overview of the game’s rules, the overall goal, and details on how the AI works using a Pure Monte Carlo Tree Search approach.
- It describes the simulation-based decision making (i.e., playing multiple simulated games to decide the best move) and even touches on performance metrics.
- The README also emphasizes the learning objectives for the developer (React, HTML/CSS) and provides details on how to run, build, and report on the application.

- Components:
– UI Components (Board, Tile, Grid, Score, Modals)
– Game Engine components (Board, BoardMover, Direction, etc.)
– AI components (Monte Carlo Simulation, NextMoveAiWorker, WebWorker integration, ReportGenerator)
– Reporting Module (to track win ratios and move performance).
- Relationships and Interactions:
– Connections between the AI engine and Web Workers should be explicitly drawn.
- Visual Distinctions:
– Use clear labels, such as “Controller”, “Game Engine”, “AI Simulation”, “UI”, etc.

– A “Presentation Layer” block hosting all React UI components.
– A “Game Engine” block directly below that.
– An “AI Agent” block alongside or beneath the engine showing Monte Carlo simulation, with an auxiliary “Web Worker” sub-component if applicable.
– Optionally, a “Reporting & Analytics” block demonstrating flow of simulation data from AI to performance reports.
– Client actions (user inputs) trigger state updates in the Game Engine.
– The Game Engine communicates with the AI Agent for move decisions.
– The AI Agent utilizes Web Workers to perform simulations asynchronously.
– The results loop back to update the Game Engine and hence the UI.
This is the core loop for every move in the game.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        UI["React UI Components"]:::ui
    end

    subgraph "Game Engine"
        GE_Board["Board (Game State)"]:::engine
        GE_Mover["BoardMover (Movement Logic)"]:::engine
        GE_Direction["Direction (Enumeration)"]:::engine
    end

    subgraph "AI Agent"
        AI_MC["Monte Carlo Simulation"]:::ai
        AI_Next["NextMoveAiWorker (Async Move Calculation)"]:::ai
        AI_Report["ReportGenerator (Performance Logging)"]:::ai
        AI_Web["WebWorker Integration"]:::ai
    end

    subgraph "Reporting & Analytics"
        Report["Performance Reports"]:::report
    end

    subgraph "Static & Configuration"
        Public["Public Assets"]:::static
        Config["Build & Config Scripts"]:::static
    end

    %% Relationships / Data Flow
    UI -->|"triggers_game_move"| GE_Board
    GE_Board -->|"calls_logic"| GE_Mover
    GE_Mover -->|"uses_enum"| GE_Direction
    GE_Board -->|"requests_AI_move"| AI_MC
    AI_MC -->|"offloads_to"| AI_Web
    AI_Web -->|"returns_best_move"| AI_Next
    AI_Next -->|"sends_decision_to"| GE_Board
    AI_MC -->|"logs_performance"| AI_Report
    AI_Report -->|"updates"| Report
    GE_Board -->|"updates_state"| UI
    UI -->|"loads_static"| Public

    %% Click Events for Component Mapping
    click UI "https://github.com/virgs/2048-ai/tree/main/src/components"
    click GE_Board "https://github.com/virgs/2048-ai/blob/main/src/engine/Board.ts"
    click GE_Mover "https://github.com/virgs/2048-ai/blob/main/src/engine/BoardMover.ts"
    click GE_Direction "https://github.com/virgs/2048-ai/blob/main/src/engine/Direction.ts"
    click AI_MC "https://github.com/virgs/2048-ai/blob/main/src/ai/MonteCarlo.ts"
    click AI_Next "https://github.com/virgs/2048-ai/blob/main/src/ai/NextMoveAiWorker.ts"
    click AI_Report "https://github.com/virgs/2048-ai/blob/main/src/ai/ReportGenerator.ts"
    click AI_Web "https://github.com/virgs/2048-ai/blob/main/docs/WebWorker-qSx9W5au.js"
    click Report "https://github.com/virgs/2048-ai/tree/main/reports"
    click Public "https://github.com/virgs/2048-ai/tree/main/public"
    click Config "https://github.com/virgs/2048-ai/blob/main/vite.config.ts"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef engine fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef ai fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef report fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef static fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
