# xiaoxiunique/x-kit architecture

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

- Interactive diagram: https://gitdiagram.com/xiaoxiunique/x-kit
- Repository: https://github.com/xiaoxiunique/x-kit

## Overview

##### Main components
- GitHub Actions & Scheduler – Represent the automation layer with workflows (daily-get-tweet-id.yml, get-home-latest-timeline.yml, and post-twitter-daily.yml). This is the entry point for scheduling and triggering data fetching and posting.
- Core Scripts (under the scripts directory) – Include the operational scripts like index.ts (entry script), fetch-tweets.ts, fetch-user-tweets.ts, batch-follow.ts, post-tweet.ts, and utility functions (utils.ts). These scripts interact with Twitter’s API and perform functions like fetching user tweets, posting tweets, and managing follows.
- Data Storage – Two main directories:
∘ accounts/ – Storing user account JSON files, containing fetched profile information.
∘ tweets/ – Holding tweet JSON files, organized by date.
- External Services – Twitter API (accessed using provided tokens in the environmental variables) which is a critical external dependency.
- Environment & Configuration – .env file and configuration setups (e.g., dev-accounts.json) that inform the scripts about tokens and about which users to track.

##### Component relationships and interactions
- GitHub Actions periodically trigger the core scripts:
- One workflow runs every 30 minutes (get-home-latest-timeline.yml) to pull the latest timeline data.
- Another workflow (daily-get-tweet-id.yml) runs daily to update user information.
- There is also a workflow for posting daily tweets (post-twitter-daily.yml) which triggers the post-tweet.ts script.
- The core scripts:
- Use configuration from the .env file and dev-accounts.json.
- Fetch data from the Twitter API using the provided authentication tokens.
- Save or update the data in the tweets/ (for tweet data) and accounts/ (for user profiles) directories.
- Some scripts (like batch-follow.ts) perform actions based on the fetched user data.
- There is also a logical flow from scheduled tasks → execution of scripts → data retrieval → data storage.

##### Architectural patterns and design principles
- Automation and Scheduling – The use of GitHub Actions ensures that tasks are automated and scheduled without manual intervention.
- Modular Script Design – The division of functional responsibilities across multiple TypeScript scripts in the scripts folder allows for clear separation of concerns.
- File-based Data Persistence – The design uses JSON files stored in organized directories (accounts and tweets) to maintain a persistent local state.
- Environment-based Configuration – Reliance on environment variables (.env) and developer configuration files (dev-accounts.json) to drive behavior.

##### Relevant technologies and libraries
- Runtime: Bun
- Language: TypeScript
- External API: Twitter API
- CI/CD: GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub Actions Scheduler"
        GA1["daily-get-tweet-id.yml"]:::scheduler
        GA2["get-home-latest-timeline.yml"]:::scheduler
        GA3["post-twitter-daily.yml"]:::scheduler
    end

    subgraph "x-kit Engine"
        Engine["x-kit Engine (Bun + TypeScript Scripts)
index.ts, fetch-tweets.ts,
fetch-user-tweets.ts,
batch-follow.ts, post-tweet.ts,
utils.ts"]:::engine
    end

    subgraph "Local Data Storage"
        accountsStorage["accounts/"]:::storage
        tweetsStorage["tweets/"]:::storage
    end

    Config["Configuration & Environment
(.env & dev-accounts.json)"]:::config
    twitterAPI["Twitter API"]:::external

    %% Data Flow
    GA1 -->|"triggers"| Engine
    GA2 -->|"triggers"| Engine
    GA3 -->|"triggers"| Engine

    Config -->|"configures"| Engine
    Engine -->|"fetches from"| twitterAPI
    Engine -->|"stores data in"| accountsStorage
    Engine -->|"stores data in"| tweetsStorage

    %% Click Events
    click GA1 "https://github.com/xiaoxiunique/x-kit/blob/main/.github/workflows/daily-get-tweet-id.yml"
    click GA2 "https://github.com/xiaoxiunique/x-kit/blob/main/.github/workflows/get-home-latest-timeline.yml"
    click GA3 "https://github.com/xiaoxiunique/x-kit/blob/main/.github/workflows/post-twitter-daily.yml"
    click Engine "https://github.com/xiaoxiunique/x-kit/tree/main/scripts"
    click accountsStorage "https://github.com/xiaoxiunique/x-kit/tree/main/accounts"
    click tweetsStorage "https://github.com/xiaoxiunique/x-kit/tree/main/tweets"
    click Config "https://github.com/xiaoxiunique/x-kit/blob/main/dev-accounts.json"

    %% Styles
    classDef scheduler fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef engine fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef storage fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef config fill:#fad7a0,stroke:#f39c12,stroke-width:2px;
```
