# mic-hb/proyek_ai_backend architecture

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

- Interactive diagram: https://gitdiagram.com/mic-hb/proyek_ai_backend
- Repository: https://github.com/mic-hb/proyek_ai_backend

## Overview

##### Project Type and Purpose
- This is a **backend AI service** for the traditional Indonesian game “Macan-Macanan.”
- It exposes a **Socket.IO** API (real-time events) and houses both the **game rule engine** and multiple **AI algorithms** (Minimax with alpha-beta pruning).

a. **Client**
- Any front-end or UI (web/mobile) that uses Socket.IO to interact with the server.
b. **Socket.IO Server Layer (src/app/api.py)**
- Listens for connection, room-join, move requests, AI-suggestion requests.
- Emits game state updates and AI moves back to clients.
c. **Game Engine (src/game/…)**
- Domain model: Board, Cell, Piece, Player, Room.
- Game rules and state transitions (game.py, move_request.py, suggested_move.py).
d. **AI Service Layer (src/app/ai.py)**
- Orchestrates calls to specific algorithms based on game state.
e. **Algorithm Modules (src/ai/…)**
- algorithm_1.py, algorithm_2.py implement Minimax / alpha-beta.
- AI.py defines common interfaces for algorithms.
f. (Optional) **Persistence / Configuration**
- Even if no database is used, show configuration (pyproject.toml, requirements.txt, .env, if any) and test harness (tests/).

##### Relationships and Data Flows
- **Client → Socket.IO Server**: emits events like “join_room,” “make_move,” “request_suggestion.”
- **Socket.IO Server → Game Engine**: invokes game logic to validate/apply moves.
- **Socket.IO Server → AI Service → Algorithm Modules**: for “suggest_move” events.
- **Game Engine / AI → Socket.IO Server → Client**: emits updated game state or AI-chosen move.

##### Architectural Patterns & Design Principles
- **Separation of Concerns**:
- API layer handles connectivity & protocol.
- Game engine encapsulates pure domain logic.
- AI layer wraps algorithms.
- **Modularity/Plug-in Architecture**: new AI algorithms can be dropped into src/ai/ and wired in src/app/ai.py.
- **Event-Driven**: Socket.IO events drive the flow.

##### Technologies & Frameworks to Annotate
- **Python 3.12** (interpreter)
- **python-socketio** (server implementation)
- **Minimax & Alpha-Beta Pruning** techniques (in algorithm modules)
- **pytest** (tests suite)
- **Sphinx** (in docs/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["External Client (Socket.IO)"]:::external

    subgraph "Server"
        subgraph "API Layer"
            API["src/app/api.py\n(Socket.IO Handlers)"]:::api
        end
        subgraph "Game Engine"
            Board["src/game/board.py"]:::domain
            Cell["src/game/cell.py"]:::domain
            Piece["src/game/piece.py"]:::domain
            Player["src/game/player.py"]:::domain
            Room["src/game/room.py"]:::domain
            Game["src/game/game.py"]:::domain
            MoveReq["src/game/move_request.py"]:::domain
            SugMove["src/game/suggested_move.py"]:::domain
            Const["src/game/constants.py"]:::domain
        end
        subgraph "AI Service Layer"
            AIService["src/app/ai.py\n(AI Orchestration)"]:::service
        end
        subgraph "Algorithm Modules"
            AIIfc["src/ai/AI.py"]:::algorithm
            Algo1["src/ai/algorithm_1.py"]:::algorithm
            Algo2["src/ai/algorithm_2.py"]:::algorithm
        end
    end

    subgraph "Configuration & CI"
        PyProj["pyproject.toml"]:::config
        Req["requirements.txt"]:::config
        Pylint[".pylintrc"]:::config
        Ruff["ruff.toml"]:::config
        Travis[".travis.yml"]:::config
        Tox["tox.ini"]:::config
    end

    subgraph "Documentation"
        Conf["docs/conf.py"]:::docs
        Index["docs/index.rst"]:::docs
        Usage["docs/usage.rst"]:::docs
        Install["docs/installation.rst"]:::docs
        Contrib["docs/contributing.rst"]:::docs
        Authors["docs/authors.rst"]:::docs
        History["docs/history.rst"]:::docs
    end

    subgraph "Tests"
        TestInit["tests/__init__.py"]:::test
        TestSuite["tests/test_proyek_ai_backend.py"]:::test
    end

    %% Flows
    Client -->|"join_room / make_move / request_suggestion"| API
    API -->|"process_move"| MoveReq
    MoveReq -->|"validate/apply"| Game
    Game -->|"state_update"| API
    API -->|"emit 'move_made'"| Client

    API -->|"suggest_move"| AIService
    AIService -->|"interface call"| AIIfc
    AIIfc -->|"use"| Algo1
    AIIfc -->|"use"| Algo2
    Algo1 -->|"result"| AIService
    Algo2 -->|"result"| AIService
    AIService -->|"compute suggestion"| SugMove
    SugMove -->|"suggested_move update"| API
    API -->|"emit 'suggestion'"| Client

    %% Click Events
    click API "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/app/api.py"
    click AIService "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/app/ai.py"
    click Board "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/board.py"
    click Cell "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/cell.py"
    click Piece "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/piece.py"
    click Player "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/player.py"
    click Room "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/room.py"
    click Game "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/game.py"
    click MoveReq "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/move_request.py"
    click SugMove "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/suggested_move.py"
    click Const "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/game/constants.py"
    click AIIfc "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/ai/AI.py"
    click Algo1 "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/ai/algorithm_1.py"
    click Algo2 "https://github.com/mic-hb/proyek_ai_backend/blob/main/src/ai/algorithm_2.py"
    click PyProj "https://github.com/mic-hb/proyek_ai_backend/blob/main/pyproject.toml"
    click Req "https://github.com/mic-hb/proyek_ai_backend/blob/main/requirements.txt"
    click Pylint "https://github.com/mic-hb/proyek_ai_backend/blob/main/.pylintrc"
    click Ruff "https://github.com/mic-hb/proyek_ai_backend/blob/main/ruff.toml"
    click Travis "https://github.com/mic-hb/proyek_ai_backend/blob/main/.travis.yml"
    click Tox "https://github.com/mic-hb/proyek_ai_backend/blob/main/tox.ini"
    click Conf "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/conf.py"
    click Index "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/index.rst"
    click Usage "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/usage.rst"
    click Install "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/installation.rst"
    click Contrib "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/contributing.rst"
    click Authors "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/authors.rst"
    click History "https://github.com/mic-hb/proyek_ai_backend/blob/main/docs/history.rst"
    click TestInit "https://github.com/mic-hb/proyek_ai_backend/blob/main/tests/__init__.py"
    click TestSuite "https://github.com/mic-hb/proyek_ai_backend/blob/main/tests/test_proyek_ai_backend.py"

    %% Styles
    classDef external fill:#f9f,stroke:#333,color:#000;
    classDef api fill:#bbf,stroke:#333,color:#000;
    classDef service fill:#bfb,stroke:#333,color:#000;
    classDef domain fill:#fbf,stroke:#333,color:#000;
    classDef algorithm fill:#ffb,stroke:#333,color:#000;
    classDef config fill:#ddd,stroke:#333,color:#000;
    classDef docs fill:#cff,stroke:#333,color:#000;
    classDef test fill:#fcc,stroke:#333,color:#000;
```
