How xiaoxiunique/x-kit works
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