# girik21/twitter-bot architecture

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

- Interactive diagram: https://gitdiagram.com/girik21/twitter-bot
- Repository: https://github.com/girik21/twitter-bot

## Overview

##### Project type and purpose
- This is an automated backend “Twitter bot” service written in Node.js.
- Purpose: Every hour (via cron), fetch top Hacker News stories, pass them to Google Gemini to generate click-bait AI/ML tweets, post one tweet via Twitter API, and record the tweet in a Supabase database.

##### File structure
- index.js: entry point, orchestrates the hourly run
- genAi/: contains geminiIntegration.js (calls Gemini API) and tweetSchema.js (defines prompt/schema for tweets)
- news/: newsFetcher.js (fetches top HN stories)
- utils/: helper modules—demo.js (local testing), saveTweetsToFile.js (persisting to disk), supabaseTracker.js (logging to Supabase)
- output/: .gitignore (likely holds saved tweets when running in demo)
- package.json, .env references for API keys, and deployment config implied (Render.com cron)

##### README for additional insights
- Runtime: Node ≥18
- External services: Google Gemini API, Twitter API v2, Supabase
- Deployment: Render.com with hourly cron trigger

a. Main components
- Scheduler (Render.com cron)
- Node.js application (index.js)
– newsFetcher module
– Gemini integration module
– Twitter client module
– Supabase tracker module
- External Services: Hacker News API, Google Gemini API, Twitter API, Supabase Database
- Optional local storage (output folder) for demo or logs

b. Relationships & data flow
1. Scheduler invokes the Node.js app every hour
2. App calls newsFetcher → retrieves top stories from Hacker News
3. Pass stories to GeminiIntegration → receives generated tweet text
4. Send one tweet to Twitter API → receives tweet ID/metadata
5. Call SupabaseTracker → insert record of posted tweet
6. (Optional) Save tweet to file via saveTweetsToFile for local audit or demo

c. Architectural patterns & design principles
- Modular pipeline: each step in its own module (single responsibility)
- Event-driven by cron scheduler
- External integrations abstracted behind thin adapters (geminiIntegration, supabaseTracker)
- Idempotency/tracking via Supabase to avoid reposts

d. Key technologies/frameworks
- Node.js (runtime)
- Axios or fetch (HTTP calls in modules)
- Google Gemini API
- Twitter API v2 SDK or REST calls
- Supabase JS client
- Render.com cron jobs

## Diagram (Mermaid)

```mermaid
flowchart TD
    Scheduler("Render.com Cron"):::infra
    Scheduler -->|"Triggers hourly run"| AppEntry

    subgraph "Backend Bot (Node.js)" 
        AppEntry["index.js"]:::internal
        News["News Fetcher"]:::internal
        Schema["Tweet Schema"]:::internal
        AI["AI Generator"]:::internal
        Poster["Twitter Poster"]:::internal
        DBTracker["Supabase Tracker"]:::internal
        Demo["Demo Helper"]:::internal
        SaveFile["SaveTweetsToFile"]:::internal
        Output["Output Storage"]:::internal
    end

    AppEntry -->|"calls newsFetcher"| News
    News -->|"GET top stories"| HNAPI["Hacker News API"]:::external
    HNAPI -->|"returns stories"| News

    News -->|"passes stories"| Schema
    Schema -->|"structured prompt"| AI
    AI -->|"POST prompt"| GeminiAPI["Google Gemini API"]:::external
    GeminiAPI -->|"returns tweet text"| AI

    AI -->|"generates tweet"| Poster
    Poster -->|"POST tweet"| TwitterAPI["Twitter API v2"]:::external
    TwitterAPI -->|"returns tweet metadata"| Poster

    Poster -->|"records metadata"| DBTracker
    DBTracker -->|"INSERT record"| SupabaseDB["Supabase Database"]:::external

    AppEntry -->|"if demo mode"| Demo
    Demo --> SaveFile
    SaveFile -->|"writes file"| Output

    Env["Environment Variables\n(GEMINI_API_KEY,\nTWITTER_*, SUPABASE_*)"]:::infra
    AppEntry --> Env

    click AppEntry "https://github.com/girik21/twitter-bot/blob/master/index.js"
    click News "https://github.com/girik21/twitter-bot/blob/master/news/newsFetcher.js"
    click Schema "https://github.com/girik21/twitter-bot/blob/master/genAi/tweetSchema.js"
    click AI "https://github.com/girik21/twitter-bot/blob/master/genAi/geminiIntegration.js"
    click DBTracker "https://github.com/girik21/twitter-bot/blob/master/utils/supabaseTracker.js"
    click SaveFile "https://github.com/girik21/twitter-bot/blob/master/utils/saveTweetsToFile.js"
    click Demo "https://github.com/girik21/twitter-bot/blob/master/utils/demo.js"
    click Output "https://github.com/girik21/twitter-bot/tree/master/output/"

    classDef internal fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef external fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#333,stroke-width:1px
```
