# rey-allan/ants architecture

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

- Interactive diagram: https://gitdiagram.com/rey-allan/ants
- Repository: https://github.com/rey-allan/ants

## Overview

##### Project Type & Purpose
- The project is a game simulation and AI research platform that recreates an online challenge.
- Its core components (game logic, map handling, entities, and replay functionality) are written in Rust, with Python acting as an interface layer (wrappers, visualization, and additional logic).
- The README and file tree indicate that the package facilitates AI research by offering an engine that can be integrated with custom AI agents, plus examples to get started.

##### Analyzing the File Structure
- At the root, you have infrastructure for CI (under .github) and a clean LICENSE, README, etc.
- Under the “ants_ai” directory:
- Files like Cargo.lock, Cargo.toml, and pyproject.toml indicate a Rust project that is exposed to Python (typically via FFI bindings).
- The “src” folder holds Rust modules (entities, game, map, replay, lib) that form the core game engine.
- The “ants_ai/ants_ai” subdirectory contains Python modules (e.g., __init__.py, visualizer.py, env.py) that likely serve as the Python API for interacting with the Rust engine.
- The “assets” folder probably contains game assets (graphics, configuration, etc.), which may be used by the visualizer or game components.
- The “examples” folder has sample maps and tutorial scripts (both in Python and Rust) to help users understand and integrate with the project.

##### Main Components
a. Core Game Engine (Rust):
- Modules: lib.rs (entry point), entities.rs, game.rs, map.rs, replay.rs.
- This component implements the core logic of the simulation, game rules, and data handling.

b. Python Interface & Wrappers:
- Modules: __init__.py, env.py, visualizer.py, and the accompanying py.typed file.
- Provides a high-level API and visualization capabilities wrapping the Rust game engine.

c. Assets:
- Contains static resources (graphics, game configurations, etc.) used by the visualizer or game logic.

d. Examples & Tutorials:
- Located in the examples directory, these scripts (Python and Rust) and maps help users learn how to use the system.

e. CI/Deployment:
- CI workflows (under .github/workflows) which are used for integration and automated testing.

##### Relationships and Interactions
- The Python Interface acts as a bridge between the end-user (or any high-level application) and the underlying Rust engine.
- The core game engine in Rust handles all simulation and game logic; it exposes its functionality via Foreign Function Interfaces (or similar integration) to the Python modules.
- The visualizer (Python) communicates with the game engine to render the simulation’s state using assets.
- The examples demonstrate integration by invoking Python wrappers (or Rust APIs) and interacting with both the game engine and visualizer.
- CI/CD pipelines ensure that changes to both Rust and Python parts pass tests, encouraging smooth integration.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The system separates the performance-critical game logic (Rust) from the high-level control and visualization (Python).
- Layered Architecture: Core engine (data and logic layer) is distinct from the presentation/interaction layer (Python interface).
- Integration and Extensibility: The use of examples and Python wrappers encourages users to extend and plug in their own AI agents.

##### Elements
- Clear, labeled blocks for each major component:
- Core Game Engine (with modules: game, entities, map, replay, lib)
- Python Interface/Wrappers (with modules: __init__.py, env.py, visualizer.py)
- Assets (game assets/resources)
- Example Applications and Tutorials (both Python and Rust variants)
- CI/CD Pipeline (GitHub workflows)
- How the Python layer communicates with the Rust engine.
- Data flow between the visualizer and game engine.
- Integration of example scripts as clients.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Example Clients
    subgraph "Example / Tutorial Clients"
        EX("Examples & Tutorials"):::example
    end

    %% Python API/Visualization Layer
    subgraph "Python API/Visualization Layer"
        PY("Python Interface & Wrappers"):::python
        PY1("__init__.py"):::python
        PY2("env.py"):::python
        PY3("visualizer.py"):::python
        PY --> PY1
        PY --> PY2
        PY --> PY3
    end

    %% Core Game Engine (Rust)
    subgraph "Core Game Engine (Rust)"
        RUST("Core Game Engine"):::rust
        R1("lib.rs"):::rust
        R2("entities.rs"):::rust
        R3("game.rs"):::rust
        R4("map.rs"):::rust
        R5("replay.rs"):::rust
        RUST --> R1
        RUST --> R2
        RUST --> R3
        RUST --> R4
        RUST --> R5
    end

    %% Supporting Components
    subgraph "Supporting Components"
        AS("Assets"):::asset
        CI("CI/CD Pipeline"):::ci
    end

    %% Data flow connections
    EX -->|"calls"| PY
    PY -->|"invokes_game_engine"| RUST
    RUST -->|"returns_state"| PY
    PY -->|"uses_assets"| AS
    EX -->|"demonstrates_integration"| AS
    CI -.-> RUST
    CI -.-> PY

    %% Click Events
    click RUST "https://github.com/rey-allan/ants/tree/main/ants_ai/src"
    click PY "https://github.com/rey-allan/ants/tree/main/ants_ai/ants_ai"
    click AS "https://github.com/rey-allan/ants/tree/main/ants_ai/ants_ai/assets"
    click EX "https://github.com/rey-allan/ants/tree/main/ants_ai/examples"
    click CI "https://github.com/rey-allan/ants/blob/main/.github/workflows/CI.yml"

    %% Styles
    classDef rust fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef python fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef asset fill:#ccccff,stroke:#0000ff,stroke-width:2px;
    classDef ci fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef example fill:#e6e6e6,stroke:#666666,stroke-width:2px;
```
