# xpmatteo/auto-cca architecture

> Architecture diagram of the GitHub repository xpmatteo/auto-cca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xpmatteo/auto-cca
- Repository: https://github.com/xpmatteo/auto-cca

## Overview

##### Project Type and Purpose
- This is a browser-based educational AI application for exploring Monte-Carlo Tree Search on a complex board game.
- It consists of a game engine (model), multiple AI players (MCTS, greedy, open-loop), a graphical front-end, test suites, scripts for batch runs and visualization, and CI integration.

##### Top-Level Structure
- index.html
- src/
- view/ (canvas drawing, asset loader)
- model/ (game state, phases, commands)
- ai/ (player implementations, MCTS, score functions)
- lib/ (utility modules: random, combinatorial, hex math)
- interactive_game.js (Controller tying UI ↔ model ↔ AI)
- main.js (entry point)
- config.js (AI parameters)
- script/ (CLI helpers: arena simulation, timed runs, tree generation)
- doc/ (Graphviz templates)
- images/ (game graphics)
- tests and snapshots (Jest-based)
- CI config (.github/workflows/ci.yml) and Makefile

##### Core Components and Their Roles
- View Layer (src/view + index.html + images)
- Draws board, units, UI controls
- Emits user events (“End phase”, “AI continue”)
- Controller Layer (interactive_game.js, main.js)
- Initializes game, wires UI events to model updates
- Invokes AI when it’s the AI’s turn
- Model Layer (src/model)
- Encodes game rules, commands, phases, scenarios
- Maintains current game state
- AI Layer (src/ai)
- Implements GreedyPlayer, OpenLoopMctsPlayer, macro-move sampling
- Queries model to simulate playouts and pick next command
- Utility Modules (src/lib)
- Provide common functions used by model and AI
- Configuration (src/config.js)
- Sets iteration counts, delays, thresholds, scenario keys
- Scripts & Tools
- Batch simulation (script/arena.js)
- Tree visualization (script/tree_main.js + doc/close-combat.dot)
- Test runners (Makefile, jest.config.mjs, script/test.sh)
- CI Pipeline (GitHub Actions)
- Lints, runs tests on each PR

##### Component Interactions
- User clicks UI button → Controller receives event
- Controller calls Model.applyCommand() → Model updates state
- If it’s AI’s turn → Controller calls AI.selectCommand(modelState)
- AI consults Model via simulate playouts → returns a Command
- Controller applies AI’s Command → Model updates
- View renders updated board

##### Architectural Patterns and Principles
- MVC-style separation: Model (game rules), View (graphics), Controller (event orchestration)
- Modular design: each subsystem in its own folder, easy to stub/mock in tests
- Dependency inversion: Controller depends on interfaces of Model and AI
- Flyweight (planned) for commands to reduce object churn in MCTS

##### Technologies and Frameworks
- JavaScript ES modules (Node & Browser)
- HTML5 Canvas API for rendering
- Jest for unit tests and snapshots
- NPM & Makefile for builds and scripts
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Application Layers
    subgraph "View Layer" 
        direction TB
        ViewHTML["index.html"]:::view
        ViewSrc["src/view"]:::view
        Images["images"]:::view
    end

    subgraph "Controller Layer"
        direction TB
        Interactive["interactive_game.js"]:::controller
        MainJS["main.js"]:::controller
        TreeMain["tree_main.js"]:::controller
    end

    subgraph "Model & AI" 
        direction TB
        subgraph "Model Layer"
            direction TB
            ModelSrc["src/model"]:::model
        end
        subgraph "AI Layer"
            direction TB
            AISrc["src/ai"]:::ai
        end
    end

    %% Utilities, Config and External Tools
    Utilities["src/lib"]:::utils
    Config["src/config.js"]:::config
    Scripts["script"]:::external
    Docs["doc/close-combat.dot"]:::external
    CI[".github/workflows/ci.yml"]:::external
    Build["Makefile, jest.config.mjs, tsconfig.json"]:::external

    %% Data Flows & Events
    ViewHTML -->|"User clicks"| Interactive
    Interactive -->|"applyCommand()"| ModelSrc
    ModelSrc -->|"returns new state"| Interactive
    Interactive -->|"draw()"| ViewSrc

    Interactive -->|"selectCommand()"| AISrc
    AISrc -->|"simulate playouts"| ModelSrc
    AISrc -->|"returns Command"| Interactive

    %% Utility and Config connections
    Utilities -.->|imports| ModelSrc
    Utilities -.->|imports| AISrc
    Config -.->|parameters| AISrc
    Config -.->|parameters| Interactive

    %% External Tools
    Scripts -.->|batch runs| ModelSrc
    Scripts -.->|tree gen| AISrc
    Docs -.->|templates| Scripts
    CI -.->|runs tests| ModelSrc
    CI -.->|runs tests| AISrc
    Build -.->|build & test| CI

    %% Click Events
    click ViewHTML "https://github.com/xpmatteo/auto-cca/blob/main/index.html"
    click ViewSrc "https://github.com/xpmatteo/auto-cca/tree/main/src/view/"
    click Images "https://github.com/xpmatteo/auto-cca/tree/main/images/"
    click Interactive "https://github.com/xpmatteo/auto-cca/blob/main/src/interactive_game.js"
    click MainJS "https://github.com/xpmatteo/auto-cca/blob/main/src/main.js"
    click TreeMain "https://github.com/xpmatteo/auto-cca/blob/main/src/tree_main.js"
    click ModelSrc "https://github.com/xpmatteo/auto-cca/tree/main/src/model/"
    click AISrc "https://github.com/xpmatteo/auto-cca/tree/main/src/ai/"
    click Utilities "https://github.com/xpmatteo/auto-cca/tree/main/src/lib/"
    click Config "https://github.com/xpmatteo/auto-cca/blob/main/src/config.js"
    click Scripts "https://github.com/xpmatteo/auto-cca/tree/main/script/"
    click Docs "https://github.com/xpmatteo/auto-cca/blob/main/doc/close-combat.dot"
    click CI "https://github.com/xpmatteo/auto-cca/blob/main/.github/workflows/ci.yml"
    click Build "https://github.com/xpmatteo/auto-cca/tree/main/Makefile"

    %% Legend
    subgraph Legend
        direction TB
        A["→ Solid arrow : direct function call / data flow"]
        B["---> Dashed arrow : event emission or callback"]
        C["Blue : View/UI"]
        D["Green : Controller"]
        E["Orange : Model"]
        F["Red : AI"]
        G["Gray : Utilities / Config / External Tools"]
    end

    %% Styles
    classDef view fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef controller fill:#d4edda,stroke:#28a745,color:#155724;
    classDef model fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef ai fill:#f8d7da,stroke:#dc3545,color:#721c24;
    classDef utils fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41;
```
