# david-patrick-chuks/instagram-ai-agent architecture

> Architecture diagram of the GitHub repository david-patrick-chuks/instagram-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/david-patrick-chuks/instagram-ai-agent
- Repository: https://github.com/david-patrick-chuks/instagram-ai-agent

## Overview

##### Project Type and Purpose
- The project is an AI-powered automation tool for Instagram, with planned expansion to other platforms (Twitter and GitHub).
- Its main features include automating social media interactions (liking, commenting, posting), AI-driven content generation (using Google Generative AI), handling proxies, and cookie management.
- The tool is split between AI “agent” functionality and client-specific scripts for interacting with various social platforms.

##### File Structure
- Top-Level Directories and Files:
– The “src” directory contains all the source code.
– “src/Agent” holds AI logic, training data, character definitions, and training scripts. This is where the central “brain” of the application resides.
– “src/client” contains modules for different social media interactions. For instance, dedicated folders for Instagram (IG-bot), Twitter, and GitHub.
– “src/config” includes configurations such as database and logger, ensuring that environment and application-level settings are centralized.
– “src/services”, “src/utils”, and “src/test” further modularize other concerns like core services, utility functions (handling downloads, cookie management, etc.), and test scripts respectively.
- Build and Configuration Files:
– Files like package.json, tsconfig.json, and .env.example indicate that this is a Node.js/TypeScript project with clear instructions for dependency management and environment setup.
- The segregation of “Agent” and “client” directories hints at a clear separation between the AI-driven content generation (including training with varied inputs such as PDFs, audio, and scraped websites) and the actual integration with social media platforms.

##### README for Additional Insights
- The README highlights the tool’s purpose, usage instructions, and planned additional agents (Twitter and GitHub).
- There is an emphasis on AI-powered content generation and automation for Instagram, while also outlining how users can supply different kinds of training inputs.
- The roadmap provided (upcoming features for Twitter and GitHub) shows that while the current focus is on Instagram, the design needs to accommodate expansion.

a. Main Components:
– Agent Component: This includes the AI logic, content generation, training (handled in src/Agent and its subdirectories). Also include schema definitions related to training and content (e.g., src/Agent/schema).
– Client Modules:
- Instagram Client (src/client/Instagram.ts and src/client/IG-bot) – for Instagram automation tasks.
- Upcoming Twitter Client (src/client/Twitter.ts and src/client/X-bot) – for future Twitter functionalities.
- Planned GitHub Client (referenced in README) – for GitHub automation.
– Configuration & Core Utilities: Modules in src/config (for logging, database configurations) and src/utils (helper functions, download utility).
– Supporting Services: Elements found in src/services (to aggregate and coordinate between AI agent, client modules, and external operations).
– Test and Helper Scripts: Under src/test and src/scripts, demonstrating the isolated testing and example generation for agent characters.

b. Relationships and Interactions:
– The Agent Component feeds generated content and training data into the Client Modules.
– Client Modules handle direct interactions with external social media platforms (Instagram, and planned Twitter and GitHub).
– Configuration and Logging are integrated with both the Agent and Client modules to manage settings and capture runtime events/ errors.
– External dependencies (like Google Generative AI, Puppeteer, and puppeteer-extra for browser automation) should be noted as libraries that interact primarily with the client modules.
– Training scripts (in Agent/training) can be depicted as feeding data into the Agent for improved content generation which then flows to the client modules.

c. Architectural Patterns and Design Principles:
– Modular design: Clear separation between AI logic (Agent) and platform-specific integration (Client).
– Separation of concerns: Configurations, utilities, and logging are centrally managed.
– Extensibility: The structure is designed to add more social media platforms with minimal changes (e.g., Twitter and GitHub modules) by following similar structural patterns.
– Error handling and logging are cross-cutting concerns maintained by the configuration module.

d. Relevant Technologies and Frameworks:
– Node.js and TypeScript as the runtime and language.
– Puppeteer (and puppeteer-extra) for browser automation.
– Google Generative AI for content generation.
– Environment variables (configured via .env) and possibly MongoDB (as indicated by MONGODB_URI).
– Other supporting libraries included via package.json.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Core Utilities
    Config["src/config – Configuration & Logger"]:::config
    Utils["src/utils – Utility Functions"]:::util

    %% AI Agent Component
    Agent["src/Agent – AI Agent Component"]:::agent
    Training["src/Agent/training – Training Module"]:::agent
    Characters["src/Agent/characters – Character Definitions"]:::agent

    %% Supporting Services
    Services["src/services – Supporting Services"]:::service

    %% External Services
    GoogleAI["Google Generative AI"]:::external
    Puppeteer["Puppeteer"]:::external
    InstagramAPI["Instagram Platform"]:::external
    TwitterAPI["Twitter Platform"]:::external
    GitHubAPI["GitHub Platform"]:::external

    %% Client Modules Subgraph
    subgraph "Instagram Client"
        IGBot["src/client/IG-bot – Instagram Automation"]:::client
        InstagramTS["src/client/Instagram.ts – Instagram Interface"]:::client
        IGBot -->|"routes to"| InstagramTS
    end

    subgraph "Twitter Client (Upcoming)"
        TwitterTS["src/client/Twitter.ts – Twitter Interface"]:::client
        XBot["src/client/X-bot – Twitter Automation"]:::client
        TwitterTS -->|"routes to"| XBot
    end

    GitHubClient["src/client/Github.ts – GitHub Automation"]:::client

    %% Test and Helper Scripts
    TestScripts["Test & Helper Scripts (src/test, src/scripts)"]:::test

    %% Connections
    Config -->|"configures"| Agent
    Utils -->|"supports"| Agent
    Agent -->|"receives training"| Training
    Agent -->|"defines personas"| Characters
    Agent -->|"coordinates via"| Services

    %% Configuration influences Clients
    Config -->|"configures"| IGBot
    Config -->|"configures"| TwitterTS
    Config -->|"configures"| GitHubClient

    %% Agent flows content to Clients
    Agent -->|"delivers content"| IGBot
    Agent -->|"delivers content"| TwitterTS
    Agent -->|"delivers content"| GitHubClient

    %% Supporting Services aids Clients
    Services -->|"assists"| IGBot
    Services -->|"assists"| TwitterTS
    Services -->|"assists"| GitHubClient

    %% Client Modules interacting with External Platforms
    IGBot -->|"API calls"| InstagramAPI
    InstagramTS -->|"browser control via"| Puppeteer

    TwitterTS -->|"API calls"| TwitterAPI
    GitHubClient -->|"API calls"| GitHubAPI

    %% External AI Service connection
    Training -->|"utilizes"| GoogleAI

    %% Test Scripts utilization
    TestScripts -->|"validates"| Agent
    TestScripts -->|"validates"| IGBot
    TestScripts -->|"validates"| TwitterTS
    TestScripts -->|"validates"| GitHubClient

    %% Click Events
    click Config "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/config"
    click Utils "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/utils"
    click Agent "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/Agent"
    click Training "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/Agent/training"
    click Characters "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/Agent/characters"
    click IGBot "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/client/IG-bot"
    click InstagramTS "https://github.com/david-patrick-chuks/instagram-ai-agent/blob/main/src/client/Instagram.ts"
    click TwitterTS "https://github.com/david-patrick-chuks/instagram-ai-agent/blob/main/src/client/Twitter.ts"
    click XBot "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/client/X-bot"
    click GitHubClient "https://github.com/david-patrick-chuks/instagram-ai-agent/blob/main/src/client/Github.ts"
    click Services "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/services"
    click TestScripts "https://github.com/david-patrick-chuks/instagram-ai-agent/tree/main/src/test"

    %% Class Styles
    classDef config fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef util fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef agent fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef client fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef service fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef test fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef external fill:#F0B27A,stroke:#E67E22,stroke-width:2px;
```
