# mr-pu/twitter-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mr-pu/twitter-agent
- Repository: https://github.com/mr-pu/twitter-agent

## Overview

##### Project Type and Purpose
- This is a full-stack automated tweeting solution that uses a Streamlit-powered web interface.
- The application schedules posts on Twitter, either by reading pre-written tweets from a file or generating tweets dynamically using CrewAI agents (Tweet Writer and Tweet Editor) along with OpenAI’s GPT models.
- It integrates with external APIs (Twitter via Tweepy and OpenAI) and uses background processing (with Threading) for scheduling tasks.

##### File Structure
- The project has a simple structure with a main application file (app.py), configuration example (.env.example), requirements, a sample tweets file (sample_tweets.txt), and documentation in the README.
- There aren’t multiple directories, so the architecture is relatively straightforward, and most of the logic is likely encapsulated in the single app.py file.

##### Main Components of the System
a. User Interface:
- Built using Streamlit for a user-friendly, interactive web interface.
- Contains configuration forms where users can set posting intervals, choose the tweet type (pre-written or AI generated), and see log/status views.

b. Bot/Scheduler and Core Logic:
- The core application (app.py) that controls the overall operation.
- Implements background task management using Threading to handle periodic tweet posting.
- Reads from the pre-written tweets file (sample_tweets.txt) when needed.

c. AI Generation Component:
- Two CrewAI agents: Tweet Writer (to generate tweet drafts) and Tweet Editor (to refine tweets).
- Utilizes the OpenAI GPT models for AI content generation.

d. Twitter API Integration:
- Uses Tweepy for interacting with Twitter’s API to post tweets.
- Handles authentication managing via environment variables (configured using .env).

e. Logging and Monitoring:
- Maintains logs (e.g., twitter_agent.log) that are displayed in the interface.
- Provides real-time status updates for the posted tweets and agent status.

##### Relationships and Interactions
- The UI (Streamlit) allows users to:
- Input configuration settings (posting interval, tweet options, etc.)
- Initiate or halt the tweet scheduling process.
- Upon starting, the core logic:
- Schedules background tasks (using Threading) to check the time interval.
- Depending on configuration, either reads a tweet from sample_tweets.txt or triggers the CrewAI-driven tweet generation process.
- For the AI-driven path:
- The Tweet Writer agent generates a draft.
- The Tweet Editor agent refines that draft.
- The final tweet is then handed off to the Twitter API integration module.
- The Tweepy component manages authentication and submits the tweet to Twitter via its API.
- Log entries are generated at various stages (tweet generated, scheduled, posted, or errors) and displayed in the UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end Layer
    subgraph "Front-end Layer"
        UI["User Interface (Streamlit Web Interface)"]:::frontend
        LOG["Logging and Monitoring"]:::logging
    end

    %% Backend Layer
    subgraph "Backend Layer"
        CONFIG["Configuration (.env.example)"]:::config
        CORE["Core Application / Scheduler (app.py)"]:::backend
        FILE["Pre-written Tweets Source (sample_tweets.txt)"]:::file
        API["External API Integration (Twitter API via Tweepy & OpenAI API)"]:::external
        subgraph "AI Generation Pipeline"
            TW["Tweet Writer (AI Agent)"]:::ai
            TE["Tweet Editor (AI Agent)"]:::ai
        end
    end

    %% Connections between layers
    UI -->|"triggers"| CORE
    CONFIG -->|"configures"| CORE
    CORE -->|"reads"| FILE
    CORE -->|"initiates"| TW
    TW -->|"generates_draft"| TE
    TE -->|"finalizes"| API
    FILE -->|"provides_tweet"| API
    CORE -->|"logs_status"| LOG
    API -->|"logs_post"| LOG
    LOG -->|"displays"| UI

    %% Click Events
    click UI "https://github.com/mr-pu/twitter-agent/blob/main/app.py"
    click CORE "https://github.com/mr-pu/twitter-agent/blob/main/app.py"
    click TW "https://github.com/mr-pu/twitter-agent/blob/main/app.py"
    click TE "https://github.com/mr-pu/twitter-agent/blob/main/app.py"
    click FILE "https://github.com/mr-pu/twitter-agent/blob/main/sample_tweets.txt"
    click API "https://github.com/mr-pu/twitter-agent/blob/main/app.py"
    click CONFIG "https://github.com/mr-pu/twitter-agent/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#0b5394,stroke-width:2px;
    classDef backend fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef ai fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef file fill:#f9cb9c,stroke:#e69138,stroke-width:2px;
    classDef external fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef config fill:#c9daf8,stroke:#1155cc,stroke-width:2px;
    classDef logging fill:#ead1dc,stroke:#990033,stroke-width:2px;
```
