# existancepy/bss-macro-py-experimental architecture

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

- Interactive diagram: https://gitdiagram.com/existancepy/bss-macro-py-experimental
- Repository: https://github.com/existancepy/bss-macro-py-experimental

## Overview

##### Project type and purpose
- This is a desktop automation “macro” tool written in Python that drives the Roblox Bee Swarm Simulator game on macOS/Windows.
- It provides a local web-based GUI, a core macro engine, and a collection of functional modules (gathering, collecting, killing, planters, boosts), plus reporting and Discord integration.

##### Main components
a. Frontend (UI)
- src/webapp: static HTML/CSS/JS assets, loaded by gui.py or a minimal HTTP server.
- gui.py / main.py: bootstrap the UI, serve or open index.html in a browser/webview.
b. Backend / Core Engine
- src/main.py: orchestrates startup, loads settings, dispatches user commands to the macro subsystem.
- src/modules/macro.py: high-level macro logic, invokes submacros.
c. Modules (Business Logic)
- controls: keyboard.py, mouse.py, sleep.py → simulate input & timing.
- screen: screenshot.py, imageSearch.py, OCR, pixelColor → read game state.
- misc: settingsManager.py, appManager.py, update.py, imageManipulation.py, messageBox.py → utilities and OS integration.
- logging: log.py, webhook.py → local logs and optional webhook pushes.
- discord_bot: discordBot.py → push status/messages to a Discord server.
- submacros: gathering patterns, memoryMatch, walk, backpack, etc.
d. Data & Configuration
- settings/: user-provided paths, patterns, profiles (.py, .txt, .workflow).
- src/data/: built-in default settings, user data files.
- src/images/: reference images for GUI assets or image recognition.
e. Reporting
- src/hourly_report: static HTML pages, JavaScript/CSS, produces hourly snapshots.
f. External Services
- Discord API (via discord_bot)
- (optionally) Webhooks (via logging/webhook.py)
- Local OS services (AppleScript on macOS, window management)

##### Relationships & Data Flow
- The user interacts with the Web UI → GUI sends commands (e.g., “start gather”) to main.py.
- main.py forwards commands to the macro engine → macro.py.
- macro.py invokes the appropriate submacro(s) → submacros/*.py.
- Submacros coordinate:
- screen module to inspect game state,
- controls module to send keyboard/mouse events,
- misc module for timing and OS calls.
- All events and errors are routed through the logging module.
- Optionally, the discord_bot reports status updates to a Discord channel.
- The hourly_report component can be triggered by a scheduler or the user to generate HTML output from data in src/data and settings.

##### Architectural patterns & design principles
- Modular Separation of Concerns: each domain (controls, vision, logging, Discord, submacros) lives in its own namespace.
- MVC-style split:
- Model = settings + data files,
- View = webapp frontend,
- Controller = main.py + macro.py + modules.
- Plugin-like extensibility: new paths/patterns/submacros can be dropped into settings/ or modules/submacros.
- Single source of truth for settings: settingsManager.py loads both default and user overrides.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        UI["Web UI<br>(HTML/CSS/JS)"]:::frontend
        GUI["GUI Bootstrapper<br>gui.py"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend" 
        direction TB
        Core["Core Engine<br>main.py"]:::backend
        Macro["Macro Engine<br>macro.py"]:::backend

        subgraph "Modules" 
            direction TB

            subgraph "Controls Module" 
                direction TB
                KB["keyboard.py"]:::backend
                MS["mouse.py"]:::backend
                SL["sleep.py"]:::backend
            end

            subgraph "Screen Module" 
                direction TB
                SS["screenshot.py"]:::backend
                IS["imageSearch.py"]:::backend
                OC["ocr.py"]:::backend
                PC["pixelColor.py"]:::backend
                SD["screenData.py"]:::backend
            end

            subgraph "Misc Utilities" 
                direction TB
                SM["settingsManager.py"]:::backend
                AM["appManager.py"]:::backend
                UP["update.py"]:::backend
                IM["imageManipulation.py"]:::backend
                MB["messageBox.py"]:::backend
                AS["appleScript.py"]:::backend
            end

            subgraph "Logging" 
                direction TB
                LG["log.py"]:::backend
                WH["webhook.py"]:::backend
            end

            subgraph "Discord Integration" 
                direction TB
                DB["discordBot.py"]:::backend
            end

            Sub["Submacros<br>(plugins)"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data & Configuration" 
        direction TB
        SettingsDir["settings/"]:::data
        DefaultData["src/data/default_settings/"]:::data
        UserData["src/data/user/"]:::data
        Images["src/images/"]:::data
        PathsPatterns["settings/paths & patterns"]:::data
    end

    %% Reporting
    Reporting["Hourly Report<br>src/hourly_report/"]:::data

    %% External Services
    subgraph "External Services" 
        direction TB
        DiscordAPI["Discord API"]:::external
        WebhookAPI["Webhook Endpoints"]:::external
    end

    %% Connections
    UI -->|"HTTP request"| GUI
    GUI -->|"launch/open"| Core
    Core -->|"dispatch commands"| Macro
    Macro -->|"invokes"| Sub
    Macro -->|"calls"| KB
    Macro -->|"calls"| MS
    Macro -->|"uses"| SS
    Macro -->|"uses"| IS
    Macro -->|"uses"| OC
    Macro -->|"uses"| PC
    Macro -->|"uses"| SD
    Macro -->|"uses"| SM
    Macro -->|"uses"| AM
    Macro -->|"uses"| UP
    Macro -->|"uses"| IM
    Macro -->|"uses"| MB
    Macro -->|"uses"| AS
    KB -->|"writes & reads"| SettingsDir
    SS -->|"reads images"| Images
    Macro -->|"logs events"| LG
    LG -->|"pushes"| WebhookAPI
    DB -->|"posts status"| DiscordAPI
    Core -->|"trigger"| Reporting
    Reporting -->|"reads/writes"| DefaultData
    Reporting -->|"reads/writes"| UserData
    Reporting -->|"reads images"| Images

    %% Click Events
    click UI "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/webapp/"
    click GUI "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/gui.py"
    click Core "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/main.py"
    click Macro "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/macro.py"
    click KB "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/controls/keyboard.py"
    click MS "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/controls/mouse.py"
    click SL "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/controls/sleep.py"
    click SS "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/screen/screenshot.py"
    click IS "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/screen/imageSearch.py"
    click OC "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/screen/ocr.py"
    click PC "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/screen/pixelColor.py"
    click SD "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/screen/screenData.py"
    click SM "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/settingsManager.py"
    click AM "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/appManager.py"
    click UP "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/update.py"
    click IM "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/imageManipulation.py"
    click MB "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/messageBox.py"
    click AS "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/misc/appleScript.py"
    click LG "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/logging/log.py"
    click WH "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/logging/webhook.py"
    click DB "https://github.com/existancepy/bss-macro-py-experimental/blob/main/src/modules/discord_bot/discordBot.py"
    click Sub "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/modules/submacros/"
    click SettingsDir "https://github.com/existancepy/bss-macro-py-experimental/tree/main/settings/"
    click DefaultData "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/data/default_settings/"
    click UserData "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/data/user/"
    click Images "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/images/"
    click Reporting "https://github.com/existancepy/bss-macro-py-experimental/tree/main/src/hourly_report/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1B4F72
    classDef backend fill:#A9DFBF,stroke:#196F3D,color:#145A32
    classDef data fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef external fill:#F5B7B1,stroke:#922B21,color:#641E16
```
