# erdewit/ib_insync architecture

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

- Interactive diagram: https://gitdiagram.com/erdewit/ib_insync
- Repository: https://github.com/erdewit/ib_insync

## Overview

##### Project type and purpose
- Open-source Python library (not a multi-tier web app).
- Purpose: Simplify and unify access to Interactive Brokers’ Trader Workstation (TWS) or IB Gateway API via a high-level `IB` class, domain models (Contract, Order, Ticker, FlexReport, etc.), and an asyncio/event-driven framework.
- Includes Sphinx-based docs, Jupyter notebooks, examples, and pytest tests.

##### File structure
- Top-level package: `ib_insync/` with modules:
- connection.py, client.py, decoder.py, wrapper.py
- contract.py, order.py, ticker.py, flexreport.py, objects.py
- util.py (pandas integration), version.py, py.typed
- Directories:
- `docs/` (Sphinx source + built HTML)
- `examples/` (standalone scripts)
- `notebooks/` (Jupyter .ipynb demos)
- `tests/` (pytest tests + fixtures)
- Build & packaging: `setup.py`, `setup.cfg`, `dist.sh`, `requirements*.txt`, `.github/workflows/test.yml`.

##### README
- Confirms the async framework (asyncio + eventkit).
- Mentions domain-specific “IB component” that syncs state with TWS.
- Points at user-facing APIs, notebooks, and recipes.

##### Main components & their interactions
a. External System
- Interactive Brokers TWS or IB Gateway (TCP/IP server).
b. Core Library Components (in Python process):
- Connection Layer (`connection.py`): low-level socket I/O, message framing.
- Decoder (`decoder.py`): parses raw IB API messages into Python structures.
- Client Core (`client.py`): orchestrates requests, responses, callback dispatch.
- Wrapper (`wrapper.py`): high-level callbacks mapped to domain objects.
- IB Component (`ib.py`): top-level façade; maintains live sync with TWS, exposes req*/cancel* methods.
- Domain Models (`contract.py`, `order.py`, `ticker.py`, `flexreport.py`, `objects.py`): type definitions for IB entities.
- Event Framework: `asyncio` event loop + `eventkit` event bus for pub/sub of updates.
- Utilities (`util.py`): helpers (e.g. `df()` to convert to pandas).
- Versioning (`version.py`): package metadata.
c. User Layer
- Scripts & applications (in `examples/`).
- Jupyter notebooks (in `notebooks/`).
- External consumers import `ib_insync.IB`, call `.connect()`, issue requests, handle returned objects/events.
d. Documentation & CI
- Sphinx (`docs/`): source .rst → HTML.
- CI pipeline (`.github/workflows/test.yml`): runs pytest.
- Packaging scripts (`setup.py`, `dist.sh`).

##### Architectural patterns & principles
- Modular layering: connection → decoding → client orchestration → high-level facade.
- Event-driven: asynchronous pub/sub via asyncio/eventkit.
- Domain-driven design: separate modules for each IB domain object.
- Separation of concerns: core library vs. docs vs. examples vs. tests.

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#f88,stroke:#800,stroke-width:2px
    classDef core fill:#88f,stroke:#008,stroke-width:2px
    classDef event fill:#f8a,stroke:#c60,stroke-width:2px
    classDef user fill:#8f8,stroke:#080,stroke-width:2px
    classDef docs fill:#ccc,stroke:#666,stroke-width:2px

    subgraph "External System"
        TWS["TWS / IB Gateway"]:::external
    end

    subgraph "Core Library"
        Connection["Connection Layer"]:::core
        Decoder["Decoder"]:::core
        Client["Client Core"]:::core
        Wrapper["Wrapper"]:::core
        IBFacade["IB Façade (IB Class)"]:::core
        subgraph "Domain Models"
            Contract["Contract"]:::core
            Order["Order"]:::core
            Ticker["Ticker"]:::core
            FlexReport["FlexReport"]:::core
            Objects["Objects"]:::core
        end
        Util["Utilities (util.py)"]:::core
        Version["Versioning (version.py)"]:::core
        Typed["Type Hints Stub (py.typed)"]:::core
    end

    subgraph "Event Framework"
        EventLoop["Event Loop + EventKit"]:::event
    end

    subgraph "User Code"
        ExamplesQt["qt_ticker_table.py"]:::user
        ExamplesTk["tk.py"]:::user
        Notebooks["Jupyter Notebooks"]:::user
        ExternalApps["External Apps"]:::user
    end

    subgraph "Docs & CI"
        Sphinx["Sphinx Docs Builder"]:::docs
        HTML["Generated HTML Docs"]:::docs
        CI["CI Workflow (pytest)"]:::docs
        Packaging["Packaging Scripts"]:::docs
    end

    %% Connections
    ExamplesQt -->|imports & calls| IBFacade
    ExamplesTk -->|imports & calls| IBFacade
    Notebooks -->|imports & calls| IBFacade
    ExternalApps -->|imports & calls| IBFacade

    IBFacade -->|calls| Client
    Client -->|sends messages| Connection
    Connection -->|TCP socket| TWS
    Connection -->|frames messages| Decoder
    Decoder -->|parsed data| Client
    Client -->|dispatches| Wrapper
    Wrapper -->|updates| IBFacade

    Client -->|publishes events| EventLoop
    EventLoop -->|delivers events| ExamplesQt
    EventLoop -->|delivers events| ExamplesTk
    EventLoop -->|delivers events| ExternalApps

    Util -->|transforms to DataFrame| ExamplesQt
    Util -->|transforms to DataFrame| ExamplesTk

    Sphinx -->|reads docs & code| HTML
    CI -->|runs tests on| Connection
    CI -->|runs tests on| Decoder
    CI -->|runs tests on| Client
    CI -->|runs tests on| Wrapper
    CI -->|runs tests on| IBFacade
    CI -->|runs tests on| Contract
    CI -->|runs tests on| Order
    CI -->|runs tests on| Ticker
    CI -->|runs tests on| FlexReport
    CI -->|runs tests on| Objects

    Packaging -->|packages| Connection
    Packaging -->|packages| Client
    Packaging -->|packages| IBFacade

    %% Click Events
    click Connection "https://github.com/erdewit/ib_insync/blob/master/ib_insync/connection.py"
    click Decoder "https://github.com/erdewit/ib_insync/blob/master/ib_insync/decoder.py"
    click Client "https://github.com/erdewit/ib_insync/blob/master/ib_insync/client.py"
    click Wrapper "https://github.com/erdewit/ib_insync/blob/master/ib_insync/wrapper.py"
    click IBFacade "https://github.com/erdewit/ib_insync/blob/master/ib_insync/ib.py"
    click Contract "https://github.com/erdewit/ib_insync/blob/master/ib_insync/contract.py"
    click Order "https://github.com/erdewit/ib_insync/blob/master/ib_insync/order.py"
    click Ticker "https://github.com/erdewit/ib_insync/blob/master/ib_insync/ticker.py"
    click FlexReport "https://github.com/erdewit/ib_insync/blob/master/ib_insync/flexreport.py"
    click Objects "https://github.com/erdewit/ib_insync/blob/master/ib_insync/objects.py"
    click Util "https://github.com/erdewit/ib_insync/blob/master/ib_insync/util.py"
    click Version "https://github.com/erdewit/ib_insync/blob/master/ib_insync/version.py"
    click Typed "https://github.com/erdewit/ib_insync/blob/master/ib_insync/py.typed"
    click ExamplesQt "https://github.com/erdewit/ib_insync/blob/master/examples/qt_ticker_table.py"
    click ExamplesTk "https://github.com/erdewit/ib_insync/blob/master/examples/tk.py"
    click Notebooks "https://github.com/erdewit/ib_insync/tree/master/notebooks"
    click Sphinx "https://github.com/erdewit/ib_insync/tree/master/docs"
    click HTML "https://github.com/erdewit/ib_insync/tree/master/docs/html/"
    click CI "https://github.com/erdewit/ib_insync/blob/master/.github/workflows/test.yml"
    click Packaging "https://github.com/erdewit/ib_insync/blob/master/setup.py"
```
