# gramaddict/bot architecture

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

- Interactive diagram: https://gitdiagram.com/gramaddict/bot
- Repository: https://github.com/gramaddict/bot

## Overview

##### Project type and purpose
- GramAddict is an open-source, Python-based Instagram automation CLI tool.
- Purpose: drive user interactions (likes, follows, comments, PMs) through Android devices (physical or emulator) via adb and uiautomator2, without using Instagram’s API.

##### File structure
- Top-level CLI entrypoints:
- run.py and GramAddict/__main__.py
- Core engine (“GramAddict/core”):
- bot_flow.py (main orchestration loop)
- device_facade.py (adapter to adb/uiautomator2)
- plugin_loader.py (dynamic loading of “GramAddict/plugins”)
- session_state.py, storage.py, persistent_list.py (state & persistence)
- config.py, utils.py, decorators.py, log.py (framework services)
- navigation.py, interaction.py, scroll_end_detector.py, filter.py, views.py (UI automation primitives)
- Plugins (“GramAddict/plugins”):
- One module per action (interact_hashtag_posts.py, action_unfollow_followers.py, telegram.py, etc.)
- plugin.example demonstrates extensibility
- Configuration and data directories:
- config-examples/** (YAML, TXT samples)
- accounts/<username>/* (generated via gramaddict init)
- Extras and tooling:
- extra/configs-loader (bulk config loading)
- test/ (unit tests, mock data)
- CI and deployment files in .github/workflows
- pyproject.toml, requirements.txt, DEPLOYMENT.MD, CONTRIBUTING.md

##### README for additional insights
- Architectural outline: CLI → device (adb + uiautomator2) → Android UI
- Core patterns: “think of the bot as a stupid friend using your phone”
- Plugin architecture: installable actions, filters, reporting (Telegram API)
- External dependencies: Python 3.6+, adb tools, Android device/emulator, Telegram API for notifications

a. Main components:
- CLI Layer: run.py / gramaddict entrypoint
- Configuration Loader: parses YAML/TXT into internal models
- Core Engine: BotFlow orchestrator, State Manager, Logger, Filter Processor
- Plugin Framework: PluginLoader + individual plugin modules
- Device Facade: Adapter that wraps adb & uiautomator2 calls
- Android Device/Emulator: Instagram UI under automation
- External Services: Telegram Bot API (optional), GitHub (updates), CI/CD pipelines
- Persistence: Local files (session_state.json), persistent lists, logs
b. Relationships and interactions:
- CLI Layer calls Configuration Loader → instantiates Core Engine
- Core Engine loads plugins via PluginLoader → plugins register with BotFlow
- BotFlow issues commands (e.g., “like post”, “follow user”) to Device Facade
- Device Facade communicates over adb to uiautomator2 server on Android device
- Device performs UI interactions on Instagram App
- Plugin events can trigger Telegram notifications via the telegram plugin module
- State and metrics flow back to Core Engine → persisted to disk and logs
c. Architectural patterns and principles:
- Plugin Pattern: runtime discovery of “GramAddict/plugins” modules
- Adapter/Facade Pattern: DeviceFacade abstracts adb & uiautomator2 details
- Single Responsibility: core modules each have a narrow focus (config, logging, storage, navigation, interaction)
- Inversion of Control: BotFlow delegates specific behaviors to plugins and decorators
d. Key technologies/frameworks:
- Python 3.6+
- adb & uiautomator2 (Android UI automation)
- PyYAML for config files
- Click or argparse for CLI (implicit in __main__.py)
- PyTest for tests
- GitHub Actions for CI/CD (code-checker.yml, deploy.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        Run["run.py"]:::config
        Main["__main__.py"]:::config
    end

    subgraph "Configuration"
        ConfigLoader["config.py"]:::config
    end

    subgraph "Extras & Bulk Config"
        BulkLoader["configs_loader.py"]:::config
        BulkList["configs-list.yml"]:::config
    end

    subgraph "Core Engine"
        subgraph "Engine Modules"
            BotFlow["bot_flow.py"]:::core
            DeviceFacade["device_facade.py"]:::core
            PluginLoader["plugin_loader.py"]:::core
            SessionState["session_state.py"]:::core
            Storage["storage.py"]:::core
            PersistentList["persistent_list.py"]:::core
            Log["log.py"]:::core
            Report["report.py"]:::core
            Decorators["decorators.py"]:::core
            Utils["utils.py"]:::core
            Resources["resources.py"]:::core
            Navigation["navigation.py"]:::core
            Interaction["interaction.py"]:::core
            ScrollDetector["scroll_end_detector.py"]:::core
            Filter["filter.py"]:::core
            Views["views.py"]:::core
        end
    end

    subgraph "Plugin Framework"
        Plugins["Plugins Directory"]:::plugin
        Telegram["telegram.py"]:::plugin
    end

    subgraph "Persistence & Config Examples"
        ConfigExamples["config-examples"]:::config
    end

    subgraph "CI/CD & Tests"
        CodeRepo["Code Repository"]:::external
        CodeChecker["code-checker.yml"]:::config
        Deploy["deploy.yml"]:::config
        TestSuite["test/"]:::config
    end

    subgraph "Device & External Services"
        ADB["ADB & UIAutomator2"]:::external
        Android["Android Device/Emulator"]:::external
        TelegramAPI["Telegram Bot API"]:::external
    end

    %% Flows
    Run --> ConfigLoader
    Main --> ConfigLoader
    BulkLoader --> ConfigLoader
    ConfigLoader --> BotFlow
    BotFlow --> PluginLoader
    PluginLoader --> Plugins
    PluginLoader --> Telegram
    BotFlow --> DeviceFacade
    DeviceFacade --> ADB
    ADB --> Android
    BotFlow --> SessionState
    SessionState --> Storage
    SessionState --> PersistentList
    BotFlow --> Log
    BotFlow --> Report
    Report --> TelegramAPI
    BotFlow --> Decorators
    BotFlow --> Utils
    BotFlow --> Resources
    BotFlow --> Navigation
    Navigation --> Interaction
    Interaction --> ScrollDetector
    Interaction --> Filter
    Interaction --> Views

    CodeRepo --> CodeChecker
    CodeRepo --> Deploy
    CodeRepo --> TestSuite

    %% Click Events
    click Run "https://github.com/gramaddict/bot/blob/master/run.py"
    click Main "https://github.com/gramaddict/bot/blob/master/GramAddict/__main__.py"
    click ConfigLoader "https://github.com/gramaddict/bot/blob/master/GramAddict/core/config.py"
    click BulkLoader "https://github.com/gramaddict/bot/blob/master/extra/configs-loader/configs_loader.py"
    click BulkList "https://github.com/gramaddict/bot/blob/master/extra/configs-loader/configs-list.yml"
    click BotFlow "https://github.com/gramaddict/bot/blob/master/GramAddict/core/bot_flow.py"
    click DeviceFacade "https://github.com/gramaddict/bot/blob/master/GramAddict/core/device_facade.py"
    click PluginLoader "https://github.com/gramaddict/bot/blob/master/GramAddict/core/plugin_loader.py"
    click SessionState "https://github.com/gramaddict/bot/blob/master/GramAddict/core/session_state.py"
    click Storage "https://github.com/gramaddict/bot/blob/master/GramAddict/core/storage.py"
    click PersistentList "https://github.com/gramaddict/bot/blob/master/GramAddict/core/persistent_list.py"
    click Log "https://github.com/gramaddict/bot/blob/master/GramAddict/core/log.py"
    click Report "https://github.com/gramaddict/bot/blob/master/GramAddict/core/report.py"
    click Decorators "https://github.com/gramaddict/bot/blob/master/GramAddict/core/decorators.py"
    click Utils "https://github.com/gramaddict/bot/blob/master/GramAddict/core/utils.py"
    click Resources "https://github.com/gramaddict/bot/blob/master/GramAddict/core/resources.py"
    click Navigation "https://github.com/gramaddict/bot/blob/master/GramAddict/core/navigation.py"
    click Interaction "https://github.com/gramaddict/bot/blob/master/GramAddict/core/interaction.py"
    click ScrollDetector "https://github.com/gramaddict/bot/blob/master/GramAddict/core/scroll_end_detector.py"
    click Filter "https://github.com/gramaddict/bot/blob/master/GramAddict/core/filter.py"
    click Views "https://github.com/gramaddict/bot/blob/master/GramAddict/core/views.py"
    click Plugins "https://github.com/gramaddict/bot/tree/master/GramAddict/plugins"
    click Telegram "https://github.com/gramaddict/bot/blob/master/GramAddict/plugins/telegram.py"
    click ConfigExamples "https://github.com/gramaddict/bot/tree/master/config-examples"
    click CodeChecker "https://github.com/gramaddict/bot/blob/master/.github/workflows/code-checker.yml"
    click Deploy "https://github.com/gramaddict/bot/blob/master/.github/workflows/deploy.yml"
    click TestSuite "https://github.com/gramaddict/bot/tree/master/test/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef plugin fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
```
