# gabrielagrela/osrokbot architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielagrela/osrokbot
- Repository: https://github.com/gabrielagrela/osrokbot

## Overview

##### Project Type and Purpose
- OSROKBOT is an open-source automation tool (not a web or full-stack application) written in Python. Its purpose is to automate gameplay in “Rise of Kingdoms” by using image detection and state machines to perform predefined in-game actions (e.g., farming, scouting, captcha detection).

##### High-Level Architectural Components
a. Core Orchestrator
- OS_ROKBOT.py: the entry point that loads configuration, initializes the UI (if any), sets up state machines, and starts the automation loop.
b. State Machine Subsystem
- state_machine.py: defines the finite state machine (FSM) engine.
- action_sets.py: collections of named sequences of Actions forming distinct workflows (farm barbs, farm rss, lyceum, captcha detection).
c. Actions Subsystem
- Classes/Actions/*.py: each file implements a concrete Action class (e.g., find_and_click_image, press_key, email_action, chatgpt_action).
- action.py: base class / interface for all Actions.
d. Image Detection & OCR
- image_finder.py: wraps OpenCV template-matching logic for screenshot pattern matching.
- helpers.py: common image preprocessing (e.g., resizing, grayscale conversion) and utility functions.
- Requires external Tesseract binary for OCR (extract_text_action.py).
e. Window & Input Handling
- window_handler.py: captures screenshots of the game window, moves/clicks mouse, sends keystrokes.
- signal_emitter.py: event bus for decoupling input events and action completion signals.
f. UI & Configuration
- UI.py: optional command-line or minimal GUI interface to select which action_set to run.
- global_vars.py: shared configuration values (paths, thresholds, env variables).
- .env file (user‐provided) for API keys, email credentials, Tesseract path.
g. External Services
- OpenAI ChatGPT API (chatgpt_action.py).
- SMTP Email server (email_action.py).
- Tesseract OCR engine.
h. Media & Assets
- Media/UI: reference screenshots used for matching.
- roklyceum.csv: data file containing question/answer mapping for the Lyceum event.

##### Relationships & Data Flow
1. OS_ROKBOT.py reads .env → initializes global_vars → loads action_sets.
2. User selects workflow via UI.py (or CLI flags).
3. Core loop: state_machine invokes current Action.
4. Action (e.g., find_and_click_image) calls image_finder and window_handler:
- image_finder grabs screenshot from window_handler → runs template match → returns coordinates.
- window_handler moves mouse/clicks at returned coords.
- OCR Actions call Tesseract via subprocess on screenshots.
5. Action returns success/failure → state_machine transitions to next state.
6. Special Actions (chatgpt_action, email_action) call external APIs.
7. Loop continues until final state or quit_action is reached.

##### Architectural Patterns & Design Principles
- Modular plugin-style Actions adhering to a common interface (action.py) & discoverable via action_sets.
- Explicit FSM pattern for workflow management.
- Separation of concerns: image detection, input handling, business logic (actions), orchestration (state_machine).
- Dependency injection via global_vars and signal_emitter for loose coupling.
- Extensibility: new Actions and state_machines can be dropped into Classes/Actions and action_sets.py.

##### Detail Level
- How action_sets.py ties specific Action classes into named workflows.
- How signal_emitter decouples UI input events from automation logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Orchestrator
    subgraph "Core Orchestrator"
        OSROK["OS_ROKBOT.py\n(entry point)"]:::internal
    end

    %% State Machine
    subgraph "State Machine Subsystem"
        SM["state_machine.py\n(FSM engine)"]:::internal
        ASets["action_sets.py\n(workflows)"]:::internal
    end

    %% Actions Subsystem
    subgraph "Actions Subsystem"
        BaseAct["action.py\n(base Action interface)"]:::internal
        subgraph "Concrete Actions"
            ChatGPT["chatgpt_action.py"]:::internal
            EmailAct["email_action.py"]:::internal
            OCRAct["extract_text_action.py"]:::internal
            FindClick["find_and_click_image_action.py"]:::internal
            PressKey["press_key_action.py"]:::internal
            QuitAct["quit_action.py"]:::internal
            Others["...other Actions"]:::internal
        end
    end

    %% Image Detection & OCR
    subgraph "Image Detection & OCR"
        IFinder["image_finder.py\n(OpenCV wrapper)"]:::internal
        Helpers["helpers.py\n(preprocessing utils)"]:::internal
    end

    %% Window & Input Handling
    subgraph "Window & Input Handling"
        WH["window_handler.py\n(screenshots & input)"]:::internal
        Signal["signal_emitter.py\n(event bus)"]:::internal
    end

    %% UI & Configuration
    subgraph "UI & Configuration"
        UI["UI.py\n(CLI/GUI)"]:::internal
        GVars["global_vars.py\n(config values)"]:::internal
        ReqTxt["requirements.txt"]:::internal
        Env[".env"]:::internal
    end

    %% External Services
    Tess(OCR Engine):::external
    OpenAI("OpenAI ChatGPT API"):::external
    SMTP("SMTP Email Server"):::external

    %% Media & Assets
    MediaUI(("Media/UI\n(screenshots)")):::datastore
    Lyceum(("roklyceum.csv")):::datastore

    %% Data Flows
    OSROK -->|"loads config\ninitializes FSM"| GVars
    OSROK --> SM
    OSROK --> ASets

    SM -->|invokes| BaseAct
    ASets -->|selects Action| BaseAct

    BaseAct -->|implements| ChatGPT
    BaseAct -->|implements| EmailAct
    BaseAct -->|implements| OCRAct
    BaseAct -->|implements| FindClick
    BaseAct -->|implements| PressKey
    BaseAct -->|implements| QuitAct
    BaseAct -->|implements| Others

    ChatGPT -->|calls| OpenAI
    EmailAct -->|calls| SMTP
    OCRAct -->|spawns| Tess

    FindClick -->|uses| IFinder
    OCRAct -->|uses| IFinder
    IFinder -->|calls| WH
    WH -->|captures| MediaUI

    WH -->|emits events| Signal
    Signal --> BaseAct

    UI -->|selects workflow| ASets
    GVars -->|provides| all

    ASets -->|reads Q&A| Lyceum

    %% Click events
    click OSROK "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/OS_ROKBOT.py"
    click SM "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/state_machine.py"
    click ASets "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/action_sets.py"
    click BaseAct "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/action.py"
    click ChatGPT "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/chatgpt_action.py"
    click EmailAct "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/email_action.py"
    click OCRAct "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/extract_text_action.py"
    click FindClick "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/find_and_click_image_action.py"
    click PressKey "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/press_key_action.py"
    click QuitAct "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/Actions/quit_action.py"
    click IFinder "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/image_finder.py"
    click Helpers "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/helpers.py"
    click WH "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/window_handler.py"
    click Signal "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/signal_emitter.py"
    click UI "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/UI.py"
    click GVars "https://github.com/gabrielagrela/osrokbot/blob/master/Classes/global_vars.py"
    click ReqTxt "https://github.com/gabrielagrela/osrokbot/blob/master/requirements.txt"
    click MediaUI "https://github.com/gabrielagrela/osrokbot/tree/master/Media/UI"
    click Lyceum "https://github.com/gabrielagrela/osrokbot/blob/master/roklyceum.csv"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#21618C,stroke-width:1px;
    classDef external fill:#F5CBA7,stroke:#D35400,stroke-width:1px,stroke-dasharray: 5 5;
    classDef datastore fill:#ABEBC6,stroke:#1D8348,stroke-width:1px;
```
