# mahrtayyab/tweety architecture

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

- Interactive diagram: https://gitdiagram.com/mahrtayyab/tweety
- Repository: https://github.com/mahrtayyab/tweety

## Overview

##### Project Type and Purpose
- Type: An open-source Python SDK (client library) that reverse-engineers Twitter’s web API.
- Purpose: Expose high-level, async/sync Python methods to interact with Twitter (fetch tweets, post updates, handle streaming events, solve captchas, etc.).

##### File Structure
- Top-level:
– setup.py, pyproject.toml, requirements.txt → packaging and dependencies
– docs/ → Sphinx documentation
– src/tweety/ → main library code
- Key sub-packages under src/tweety/:
– auth.py & session.py → authentication, session management
– http.py → HTTP client wrapper
– builder.py → request/response construction
– bot.py → high-level orchestration (e.g., automated tasks)
– captcha/ → integrations with external captcha-solving services (AntiCaptcha, CapSolver, 2Captcha)
– events/ → streaming or event-based hooks (base, newmessage, stream_event)
– filters.py → helper for filtering streams/events
– transaction.py & updates.py → stateful operations (e.g., posting tweets)
– types/ → data models for various Twitter entities
– utils.py, constants.py, exceptions.py → shared utilities, constants, error classes

##### Extract Insights from README
- No internal database—pure client library
- Provides both sync (`Twitter`) and async (`TwitterAsync`) entry points
- Relies on external Twitter Web API endpoints and optional captcha-solver services
- Rate limits enforced by Twitter → error handling and retries

##### Main Components
a. User Application
– Code that imports `tweety.TwitterAsync` or `tweety.Twitter`
- Entry Points: TwitterAsync / Twitter (public API)
- Auth & Session Management: auth.py, session.py
- HTTP Layer: http.py (wrapping `requests` or `httpx`)
- Request Builder & Response Parser: builder.py
- Business Logic: bot.py, transaction.py, updates.py
- Streaming & Events: events/ + filters.py
- Captcha Integrations: captcha/ (anticaptcha, capsolver, two_captcha)
- Data Models: types/ (all `*.py` in types/)
- Common Utilities: utils.py, constants.py, exceptions.py
c. External Services:
- Twitter Frontend API (in the cloud)
- Optional Captcha-Solving APIs (AntiCaptcha, CapSolver, 2Captcha)

##### Relationships & Data Flows
- User App → calls → Entry Points (TwitterAsync)
- Entry Points → orchestrate → Auth & Session modules
- Session → issues → HTTP requests (via http.py) → Twitter API
- Twitter API → returns → HTTP responses → Builder → Data Models
- Data Models → returned → User App
- If blocked by captcha: HTTP layer delegates to Captcha module → external Captcha API → token returned → retry request
- For streaming: Entry Point → Events module → opens persistent HTTP stream → emits events → Filters → User callbacks

##### Architectural Patterns & Design Principles
- Layered Design: clear separation between transport (HTTP), business logic (bot/transaction), models (types), and entry-points
- Strategy/Plugin Pattern: captcha/ and events/ modules can be extended by adding new solver or event types
- Async vs. Sync: shared core logic, different wrappers for concurrency
- Single Responsibility: each module focuses on a narrow concern

- Clear boundary around the tweety library, subdivided by package
- Entry points at the top (sync/async) connecting to internal layers
- External dependencies and services outside the boundary

– Captures every package in `src/tweety/` as a distinct component or sub-component
– Shows how user code traverses the layers (entry → auth → HTTP → builder → models)
– Highlights optional paths (captcha solving, streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserApp["User Application"]:::user
    subgraph "tweety SDK"
        direction TB
        entry["Entry Points\nTwitter / TwitterAsync"]:::entry
        auth["Auth Module"]:::core
        session["Session Module"]:::core
        http["HTTP Layer"]:::core
        builder["Builder\n(Request/Response)"]:::core
        subgraph "Business Logic"
            direction TB
            bot["Bot Orchestration"]:::business
            transaction["Transaction"]:::business
            updates["Updates Handling"]:::business
        end
        subgraph "Streaming & Events"
            direction TB
            eventsBase["Events Base"]:::ext
            newMsg["NewMessage Handler"]:::ext
            streamEvt["StreamEvent Handler"]:::ext
            filters["Filters"]:::ext
        end
        subgraph "Captcha Integrations"
            direction TB
            capBase["Captcha Base"]:::ext
            anti["AntiCaptcha"]:::ext
            capsolver["CapSolver"]:::ext
            twoCaptcha["2Captcha"]:::ext
        end
        subgraph "Data Models"
            direction TB
            types["Types Models"]:::models
        end
        subgraph "Utils & Constants"
            direction TB
            utils["Utils"]:::core
            const["Constants"]:::core
            exc["Exceptions"]:::core
            user["User Helpers"]:::core
        end
    end
    TwitterAPI["Twitter Web API"]:::external
    CaptchaAPI["Captcha-solving APIs"]:::external

    UserApp -->|uses| entry
    entry -->|authenticate| auth
    entry -->|session| session
    session -->|request| http
    http -->|HTTP Request| TwitterAPI
    TwitterAPI -->|HTTP Response| http
    http -->|build response| builder
    builder -->|parse to models| types
    types -->|return data| UserApp
    http -->|Captcha Challenge| capBase
    capBase -->|delegates| anti
    capBase -->|delegates| capsolver
    capBase -->|delegates| twoCaptcha
    anti -->|calls| CaptchaAPI
    capsolver -->|calls| CaptchaAPI
    twoCaptcha -->|calls| CaptchaAPI
    entry -->|open stream| eventsBase
    eventsBase -->|on new message| newMsg
    eventsBase -->|on stream event| streamEvt
    newMsg -->|apply| filters
    streamEvt -->|apply| filters
    filters -->|callback| UserApp
    entry -->|bot tasks| bot
    entry -->|transactional ops| transaction
    entry -->|updates| updates

    click entry "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/__init__.py"
    click auth "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/auth.py"
    click session "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/session.py"
    click http "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/http.py"
    click builder "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/builder.py"
    click bot "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/bot.py"
    click transaction "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/transaction.py"
    click updates "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/updates.py"
    click eventsBase "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/events/base.py"
    click newMsg "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/events/newmessage.py"
    click streamEvt "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/events/stream_event.py"
    click filters "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/filters.py"
    click capBase "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/captcha/base.py"
    click anti "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/captcha/anticaptcha.py"
    click capsolver "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/captcha/capsolver.py"
    click twoCaptcha "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/captcha/two_captcha.py"
    click types "https://github.com/mahrtayyab/tweety/tree/main/src/tweety/types/"
    click utils "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/utils.py"
    click const "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/constants.py"
    click exc "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/exceptions.py"
    click user "https://github.com/mahrtayyab/tweety/blob/main/src/tweety/user.py"

    classDef entry fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef core fill:#E8F1FF,stroke:#003383,stroke-width:1px
    classDef business fill:#E8F8E0,stroke:#2E8B57,stroke-width:1px
    classDef ext fill:#FFF4E5,stroke:#D35400,stroke-width:1px
    classDef models fill:#F0F0F0,stroke:#7F8C8D,stroke-width:1px
    classDef user fill:#E8F1FF,stroke:#003383,stroke-width:1px
    classDef external fill:none,stroke:#e0245e,stroke-width:2px,stroke-dasharray: 5 5
```
