# corail-research/seahorse architecture

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

- Interactive diagram: https://gitdiagram.com/corail-research/seahorse
- Repository: https://github.com/corail-research/seahorse

## Overview

##### Main Architectural Components
- Core Game Engine: This is primarily represented by the modules under src/seahorse/game. It includes:
- Action modules (action.py, light_action.py, heavy_action.py) which likely govern player moves,
- Game state management (game_state.py),
- Game layout and board construction (src/seahorse/game/game_layout/board.py),
- The “master” module that appears to coordinate overall game flow.
- Player Management: Under src/seahorse/player, you have modules handling player logic and proxies (player.py and proxies.py). These facilitate interactions with various (possibly remote) agents.
- Utilities: Found in src/seahorse/utils, this includes custom exceptions, a GUI client, recorders, and serialization which provide cross-cutting concerns like error handling, data persistence, or UI support.
- Documentation & Tutorials: The docs folder, along with the README, contains extensive documentation and tutorials. These elements are crucial for understanding intended interactions and usage scenarios.
- CI/CD and Project Infrastructure: The .github folder with workflows shows the presence of automated testing, linting, releases, and publishing of documentation. This reflects modern development practices ensuring code quality and consistency.

##### Relationships and Interactions
- The game engine (including actions, game state, and layout) is the system’s core. Its components interact with player modules: players send actions, and the game engine processes and updates the state.
- The “master” module likely acts as a controller or coordinator that orchestrates the game flow, interfacing both with the game logic and player proxies.
- The utilities modules are invoked by both the game engine and player components to handle exceptions, record game data, serialize game state for persistence or communication, and even manage any GUI aspects for remote play.
- CI/CD workflows operate externally from the application’s runtime but are critical for continuous integration, testing, and deployment of the package (e.g., linting, testing, releasing).

##### Architectural Patterns and Design Principles
- Modularity: The project’s design is modular—dividing the game logic, player interactions, and utilities into clearly separated modules.
- Separation of Concerns: There is a clean separation between game mechanics (logic and state), player actions (and proxy communication for remote agents), and supporting functionalities like recording or serialization.
- Extensibility: The design is meant to allow users to implement new game configurations or add different player strategies with minimal friction.

##### Detail
Don’t shy away from decomposing the system into as many components as possible. Detailed separation aids in understanding each module’s responsibility and how they interplay:
- Be explicit about dependencies and data transfers—this is crucial for a thorough architectural overview.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Game Engine
    subgraph "Core Game Engine"
        subgraph "Action Management"
            GE_Action["Action Module"]:::engine
            GE_LightAction["Light Action Module"]:::engine
            GE_HeavyAction["Heavy Action Module"]:::engine
        end
        GE_GameState["Game State Management"]:::engine
        GE_Board["Game Layout/Board Construction"]:::engine
        GE_Master["Master Controller"]:::engine
    end

    %% Player Management
    subgraph "Player Management"
        PM_Player["Player Logic"]:::player
        PM_Proxies["Player Proxies"]:::player
    end

    %% Utilities
    subgraph "Utilities"
        UT_Exceptions["Custom Exceptions"]:::utils
        UT_GUI["GUI Client"]:::utils
        UT_Recorders["Recorders"]:::utils
        UT_Serializer["Serializer"]:::utils
    end

    %% External Interfaces
    DOC["Documentation & Tutorials"]:::docs

    %% CI/CD Infrastructure
    CICD["GitHub Workflows (CI/CD)"]:::cicd

    %% Relationships
    PM_Player -->|"submitAction"| GE_Action
    PM_Proxies -->|"submitAction"| GE_Action

    GE_Action -->|"updateState"| GE_GameState
    GE_LightAction -->|"updateState"| GE_GameState
    GE_HeavyAction -->|"updateState"| GE_GameState

    GE_Master -->|"orchestrates"| GE_GameState
    GE_Master -->|"buildsBoard"| GE_Board

    GE_Master <-->|"uses"| UT_Exceptions
    GE_Master <-->|"uses"| UT_GUI
    GE_Master <-->|"uses"| UT_Recorders
    GE_Master <-->|"uses"| UT_Serializer

    GE_Master -->|"recordsState"| DOC

    CICD ---|"CI/CD_Pipelines"| GE_Master
    CICD ---|"CI/CD_Pipelines"| PM_Player
    CICD ---|"CI/CD_Pipelines"| UT_Exceptions

    %% Click Events for Core Game Engine
    click GE_Action "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/action.py"
    click GE_LightAction "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/light_action.py"
    click GE_HeavyAction "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/heavy_action.py"
    click GE_GameState "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/game_state.py"
    click GE_Board "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/game_layout/board.py"
    click GE_Master "https://github.com/corail-research/seahorse/blob/main/src/seahorse/game/master.py"

    %% Click Events for Player Management
    click PM_Player "https://github.com/corail-research/seahorse/blob/main/src/seahorse/player/player.py"
    click PM_Proxies "https://github.com/corail-research/seahorse/blob/main/src/seahorse/player/proxies.py"

    %% Click Events for Utilities
    click UT_Exceptions "https://github.com/corail-research/seahorse/blob/main/src/seahorse/utils/custom_exceptions.py"
    click UT_GUI "https://github.com/corail-research/seahorse/blob/main/src/seahorse/utils/gui_client.py"
    click UT_Recorders "https://github.com/corail-research/seahorse/blob/main/src/seahorse/utils/recorders.py"
    click UT_Serializer "https://github.com/corail-research/seahorse/blob/main/src/seahorse/utils/serializer.py"

    %% Click Events for Documentation & Tutorials
    click DOC "https://github.com/corail-research/seahorse/blob/main/README.md"
    click DOC "https://github.com/corail-research/seahorse/tree/main/docs/"

    %% Click Events for CI/CD
    click CICD "https://github.com/corail-research/seahorse/tree/main/.github/workflows/"

    %% Styles
    classDef engine fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef player fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef utils fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef docs fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef cicd fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
