High‐level View Twitter Raid Flow

Term

• Raid Quest: A period of time of mission to reply relevant tweets going on indefinitely until someone hold the top leaderboard for X hours
• Raid Target: A relevant tweet to be replied by raiders
• Leaderboard entry: A tweet reply with its' metrics + Raid Quest ID + Raid Target ID

General Idea

• We can have a raid quest multiple times, for now we will control it manually to either create or end running raid quest.
• Each raid quest will have multiple raid targets.
• Each raid quest will have it's own leaderboard, this leaderboard is the result of aggregating leaderboard entries.

Tweet Search API Limitaion

• Monthly tweets pull cap of 15k
• 60 request / 15 minutes
• Each request max results 100 tweets
• Each query criteria max 512 chars

Flow

sequenceDiagram
    autonumber
    participant TM as Task Master (Cron, DB, TM API)
    participant Twitter as Twitter API
    participant TG as Raid TG
    
note over TM, TG: PHASE 1: Finding Targets (Cost: Low)
loop Every hour
    TM->>Twitter: GET /2/tweets/search/recent (Query: "(from:<whitelist>[]) Quantum")
    Twitter-->>TM: Returns up to 100 relevant tweets
    TM->>TM: Store to DB as "Relevant Tweets"
    TM->>TM: Check if there is an active raid quest
    alt Active raid found?
        TM->>TG: Forward found targets to raid telegram group
        TM->>TM: Mark relevant tweets as raid target of current active raid quest
    else No active raid
        TM->>TM: End process early
    end
end

note over TM, Twitter: PHASE 2: Update active raid leaderboard (Cost: High)
loop Every 24 Hours
    TM->>TM: Check if there is an active raid quest
    alt Active raid found?
        loop Until no more tweets to query
            TM->>Twitter: Query replies from raid targets of current raid quests
            Twitter->>TM: Returns up to 100 tweet replies
            
            loop Each tweet replies
                alt Existing entry?
                    TM->>TM: Update entry metrics
                else Not existing entry
                    TM->>TM: Store to DB as leaderboard entry
                end
            end

            alt Has more to query?
                TM->>TM: Delay 15 sec to avoid 60req/15 mins API limit
            else No more to query
                TM->>TM: End 
            end
        end
    else No active raid
        TM->>TM: End process early
    end
end

Loading

ERD

This is the database design of related tables to the raid program