# ngoxuanphong/env architecture

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

- Interactive diagram: https://gitdiagram.com/ngoxuanphong/env
- Repository: https://github.com/ngoxuanphong/env

## Overview

##### Core Components
- API Layer and Entry-Point: This is primarily provided by the root-level files such as env.py, render_template.py, and how the user interacts with the library (env.make(), env.run(), env.render()). This layer handles the interaction between an algorithm (agent) and the environment.
- Environment/Simulation Modules: The “Base” directory in src/Base contains concrete implementations of the different game environments (e.g., Catan, Durak, Splendor, etc.). Each game has its own subdirectory with its own API, rendering functions (_render_func.py), env.py, documentation, images, and other resources.
- Agent Implementations: The src/Agent directory (with its multiple subdirectories like ActionsLayer, Ifelse, BiasAlgorithm, etc.) contains various agent algorithms that either simulate strategies or help in training/testing reinforcement learning algorithms.
- Utilities & Common Infrastructure: Modules like Utils.py, env.py under src/ and in the root, plus logging components (src/Log), provide shared utility functions and support.
- Tests: The tests folder includes testing scripts (CheckEnv.py, CheckGraphics.py, test_agent.py, benchmarking notebooks) that ensure the API, environments, and agent implementations work as expected.
- Documentation & DevOps: The docs folder and the .github workflows help with developer guidelines, continuous integration, and maintaining the project quality.

##### Out Relationships and Interactions
- API Usage Flow: Show how a client (or a user script) first calls env.make() to initialize the overall environment. Then, when env.run() is called it interacts with one or more agent components (either provided by the user or chosen from the ones in src/Agent). The call to env.render() will then delegate to the appropriate environment’s visual and state-change logic found in src/Base.
- Utility and Configuration Flow: Include modules for auxiliary functions (like Utils.py, env.py), configuration files (e.g., requirements.txt, pre-commit-config.yaml) and how the CI/CD workflows (.github) support testing and deployment.
- Testing Flow: Represent the testing suite (in tests/) which uses example notebooks, benchmark notebooks, and test scripts to verify the rules, performance, and graphical output.

##### Architectural Patterns and Technologies
- Modularity and Separation of Concerns: The separation between game environments (Base), different agent implementations (Agent), and the common API (env.py and the core library logic) reinforces a plug-and-play design common in RL frameworks.
- Plugin-like Architecture: Emphasize that additional environments or agents can be added in new subdirectories, and the common API will help integrate them seamlessly.
- Standardized Interface: The design is influenced by the standard RL API (with functions for “make”, “run”, “render”, etc.), which suggests that there is a clear contract between the learning algorithm and the simulation environment.
- Technology Stack: Note that the project is built in Python (supports 3.7 to 3.10) and leverages libraries such as Numba (see njit decorator in examples) and numpy for performance and numerical computation.

##### Recommended Elements
- Clear component labeling – For example, “API/Entry Point”, “Game Environment Modules (Base)”, “Agent Implementations (Agent)”, “Utility Modules”, “Testing & CI/CD”, and “Documentation/DevOps”.
- How an API call from the user traverses into the environment.
- How agent selection and decision logic flow back to update the environment’s state.
- Optionally, include high-level examples of the data flow (e.g., “state received from environment → agent decision function returns action → environment updates game state and renders new state”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        U("User/Client"):::user
    end

    %% API/Entry Point
    subgraph "API/Entry Point"
        API_env("env.py (API)"):::api
        API_render("render_template.py (API)"):::api
        API_init("__init__.py (Core)"):::api
    end

    %% Game Environment Modules
    subgraph "Game Environment Modules"
        ENV_base("Environment Modules (Base)"):::env
        ENV_catan("Catan"):::env
        ENV_durak("Durak"):::env
        ENV_splendor("Splendor"):::env
    end

    %% Agent Implementations
    subgraph "Agent Implementations"
        AGENT_main("Agent Implementations"):::agent
        AGENT_actions("ActionsLayer"):::agent
        AGENT_ifelse("Ifelse"):::agent
        AGENT_bias("BiasAlgorithm"):::agent
    end

    %% Utilities & Infrastructure
    subgraph "Utilities & Infrastructure"
        UTIL_utils("Utils"):::util
        UTIL_env("Core Environment Logic"):::util
        UTIL_log("Logging"):::util
    end

    %% Testing Suite
    subgraph "Testing Suite"
        TESTS_main("Tests"):::test
        TESTS_bench("Benchmarks"):::test
        TESTS_checkEnv("CheckEnv"):::test
        TESTS_checkGraphics("CheckGraphics"):::test
        TESTS_agent("TestAgent"):::test
    end

    %% Documentation & DevOps
    subgraph "Documentation & DevOps"
        DOCS_docs("Docs"):::docs
        DOCS_github(".github"):::docs
        DOCS_pre("Pre-commit Config"):::docs
        DOCS_req("Requirements"):::docs
    end

    %% Connections
    U -->|"calls"| API_env

    API_env -->|"initializes"| ENV_base
    API_env -->|"selects_agent"| AGENT_main

    ENV_base -->|"contains"| ENV_catan
    ENV_base -->|"contains"| ENV_durak
    ENV_base -->|"contains"| ENV_splendor

    AGENT_main -->|"includes"| AGENT_actions
    AGENT_main -->|"includes"| AGENT_ifelse
    AGENT_main -->|"includes"| AGENT_bias

    ENV_base -->|"state_update"| API_env
    AGENT_main -->|"action_decision"| API_env

    API_env -->|"uses"| UTIL_utils
    API_env -->|"uses"| UTIL_env
    API_env -->|"uses"| UTIL_log

    TESTS_main -->|"verifies"| API_env
    TESTS_main -->|"executes"| TESTS_checkEnv
    TESTS_main -->|"executes"| TESTS_checkGraphics
    TESTS_main -->|"executes"| TESTS_agent
    TESTS_main -->|"runs"| TESTS_bench

    DOCS_docs -.->|"supports"| API_env
    DOCS_github -.->|"CI/CD"| API_env
    DOCS_req -.->|"integrates"| API_env
    DOCS_pre -.->|"configures"| API_env

    %% Styles
    classDef user fill:#ffe6e6,stroke:#000,stroke-width:1px;
    classDef api fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef env fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef agent fill:#ffffcc,stroke:#000,stroke-width:1px;
    classDef util fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef test fill:#ffb6c1,stroke:#000,stroke-width:1px;
    classDef docs fill:#ffa500,stroke:#000,stroke-width:1px;

    %% Click Events
    click API_env "https://github.com/ngoxuanphong/env/blob/main/env.py"
    click API_render "https://github.com/ngoxuanphong/env/blob/main/render_template.py"
    click API_init "https://github.com/ngoxuanphong/env/blob/main/__init__.py"
    click ENV_base "https://github.com/ngoxuanphong/env/tree/main/src/Base"
    click ENV_catan "https://github.com/ngoxuanphong/env/tree/main/src/Base/Catan"
    click ENV_durak "https://github.com/ngoxuanphong/env/tree/main/src/Base/Durak"
    click ENV_splendor "https://github.com/ngoxuanphong/env/tree/main/src/Base/Splendor"
    click AGENT_main "https://github.com/ngoxuanphong/env/tree/main/src/Agent"
    click AGENT_actions "https://github.com/ngoxuanphong/env/tree/main/src/Agent/ActionsLayer"
    click AGENT_ifelse "https://github.com/ngoxuanphong/env/tree/main/src/Agent/Ifelse"
    click AGENT_bias "https://github.com/ngoxuanphong/env/tree/main/src/Agent/BiasAlgorithm"
    click UTIL_utils "https://github.com/ngoxuanphong/env/blob/main/src/Utils.py"
    click UTIL_env "https://github.com/ngoxuanphong/env/blob/main/src/env.py"
    click UTIL_log "https://github.com/ngoxuanphong/env/tree/main/src/Log"
    click TESTS_main "https://github.com/ngoxuanphong/env/tree/main/tests"
    click TESTS_bench "https://github.com/ngoxuanphong/env/tree/main/tests/benchmarks"
    click TESTS_checkEnv "https://github.com/ngoxuanphong/env/blob/main/tests/CheckEnv.py"
    click TESTS_checkGraphics "https://github.com/ngoxuanphong/env/blob/main/tests/CheckGraphics.py"
    click TESTS_agent "https://github.com/ngoxuanphong/env/blob/main/tests/test_agent.py"
    click DOCS_docs "https://github.com/ngoxuanphong/env/tree/main/docs"
    click DOCS_github "https://github.com/ngoxuanphong/env/blob/main/.github"
    click DOCS_pre "https://github.com/ngoxuanphong/env/blob/main/.pre-commit-config.yaml"
    click DOCS_req "https://github.com/ngoxuanphong/env/blob/main/requirements.txt"
```
