# citrus610/ama architecture

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

- Interactive diagram: https://gitdiagram.com/citrus610/ama
- Repository: https://github.com/citrus610/ama

## Overview

##### Main Components
- AI Engine (ai folder): This is the heart of the project, where decision-making happens. Parse out the following submodules:
– Evaluation (eval.cpp/h): Responsible for assessing board positions.
– Form (form.cpp/h): Contains the logic for human-like chain formations.
– Gaze (gaze.cpp/h): Implements the opponent field “gazing” feature.
– Move and Path (move.cpp/h, path.cpp/h): Likely determine move sequences and board navigation.
– Search (ai/search folder): Houses different search algorithms – attack, build, and quiet search – each aimed at maximizing chain potential or tactical advantages.

- Core Game Logic (core folder): This holds the bitfield implementation and core data structures:
– Field representation (field.cpp/h, fieldbit.cpp/h)
– Essential definitions and directions (def.h, direction.h, cell.h, core.h)
This layer abstracts the state of the Puyo Puyo board and is used extensively by the AI engine.

- Client Application (puyop folder): Contains the main application (main.cpp) that starts the game and integrates the AI.

- Tuning Module (tuner folder): Provides the interface for parameter tuning (score.h, tuner.h, main.cpp) to optimize AI performance.

- Testing (test folder): Contains test harnesses that ensure the correctness of different system modules.

- External Dependencies:
– The JSON library (in lib/nlohmann) for configuration parsing.
– A configuration file (config.json) that likely sets parameters for AI behavior (e.g., enabling/disabling human-like chains).

##### Relationships and Data Flow
- The PuyoPuyo Client uses the Core Game Logic to maintain a representation of the game state.
- This state is fed into the AI Engine (evaluation, move generation, and search modules) which computes the strategic move.
- The Search submodules (attack, build, quiet) work under the umbrella of the AI Engine to simulate various strategies.
- The Tuner module operates either independently or in conjunction with the AI modules for parameter optimization and adjustments.
- External configurations (config.json) and JSON parsing via nlohmann are integrated into the initialization process to adjust AI parameters.
- The Testing suite validates the integrity of modules across layers.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each folder (ai, core, puyop, tuner, test) represents a distinct concern, from decision-making to game state management.
- Modularity: The division into submodules (especially in the ai folder with its dedicated search algorithms) suggests a plug-and-play style—each component can be updated or replaced without impacting others.
- Efficient Data Structures: The core’s bitfield implementation is central to performance and hints at using low-level optimization.
- Configuration-Driven Behavior: With a dedicated config.json and a third-party JSON library, the AI’s behavior is adjustable even post-compilation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    Config["External Config (config.json & JSON Library)"]:::external

    %% Client Application
    Client["Client Application (puyop)"]:::client

    %% Core Game Logic Layer
    subgraph "Core Game Logic"
        CoreField["Field Representation"]:::core
        CoreDef["Definitions & Directions"]:::core
    end

    %% AI Engine Layer
    subgraph "AI Engine"
        Eval["Evaluation Module"]:::ai
        Form["Form Module"]:::ai
        Gaze["Gaze Module"]:::ai
        Move["Move Module"]:::ai
        Path["Path Module"]:::ai
        subgraph "Search Algorithms"
            Attack["Attack Search"]:::ai
            Build["Build Search"]:::ai
            Quiet["Quiet Search"]:::ai
        end
    end

    %% Supporting Modules
    Tune["Tuning Module (tuner)"]:::tuner
    Test["Testing Framework"]:::testing

    %% Connections
    Config -->|"ConfigInput"| Client
    Config -->|"ConfigInput"| Eval

    Client -->|"ProvidesGameState"| CoreField
    CoreField -->|"GameStateData"| Eval

    Eval -->|"FeedsAnalysis"| Attack
    Eval -->|"FeedsAnalysis"| Build
    Eval -->|"FeedsAnalysis"| Quiet

    Tune -->|"AdjustsParameters"| Eval
    Tune -->|"AdjustsParameters"| Move

    Test -->|"Validates"| Client
    Test -->|"Validates"| CoreField
    Test -->|"Validates"| Eval
    Test -->|"Validates"| Tune

    %% Click Events
    click Config "https://github.com/citrus610/ama/blob/main/config.json"
    click Client "https://github.com/citrus610/ama/blob/main/puyop/main.cpp"
    click CoreField "https://github.com/citrus610/ama/blob/main/core/field.cpp"
    click CoreDef "https://github.com/citrus610/ama/blob/main/core/def.h"
    click Eval "https://github.com/citrus610/ama/blob/main/ai/eval.cpp"
    click Form "https://github.com/citrus610/ama/blob/main/ai/form.cpp"
    click Gaze "https://github.com/citrus610/ama/blob/main/ai/gaze.cpp"
    click Move "https://github.com/citrus610/ama/blob/main/ai/move.cpp"
    click Path "https://github.com/citrus610/ama/blob/main/ai/path.cpp"
    click Attack "https://github.com/citrus610/ama/tree/main/ai/search/"
    click Tune "https://github.com/citrus610/ama/tree/main/tuner/"
    click Test "https://github.com/citrus610/ama/blob/main/test/main.cpp"

    %% Styles
    classDef external fill:#e6ffcc,stroke:#006600,stroke-width:2px;
    classDef client fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef core fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef ai fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef tuner fill:#f0b3ff,stroke:#cc33ff,stroke-width:2px;
    classDef testing fill:#ffffcc,stroke:#ffcc00,stroke-width:2px;
```
