How gramaddict/bot works
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)