# rocky-d/wqb architecture

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

- Interactive diagram: https://gitdiagram.com/rocky-d/wqb
- Repository: https://github.com/rocky-d/wqb

## Overview

##### Project type and purpose
- This is a Python client library (a thin wrapper) for the WorldQuant BRAIN API.
- It provides a permanent, auto-refreshing HTTP session plus convenience methods for search, locate, filter, simulate, check, and submit endpoints.
- It is neither a full-stack web app nor a microservice; it is an SDK that integrates into user scripts or applications.

##### File structure
- Top-level:
- .github, CI/CD config (publish workflow)
- pyproject.toml, requirements-dev.txt (build & dev tooling)
- img (logo)
- Package root: wqb/
- auto_auth_session.py – extends requests.Session to handle automatic login & token refresh
- wqb_session.py – main class WQBSession, methods wrapping each API call (search, locate, simulate, etc.)
- wqb_urls.py – central URL constants for each REST endpoint
- datetime_range.py, filter_range.py – helpers to build query parameters (date & numeric filters)
- __init__.py – exposes public API, logger factory

##### Extract architectural insights from README
- Uses requests for synchronous calls; uses asyncio & coroutines for concurrent operations
- Logging is configurable – Console vs. File, log levels
- Permanent session with automatic authentication (“anti-expiration”)
- Exposes both limited (single-page) and streaming (generator/iterable) interfaces

##### Main components
- User Application (client script or notebook)
- wqb Python Library
a. Public API Layer (functions & classes exposed via __init__.py)
b. WQBSession – orchestrates all interactions
c. AutoAuthSession – subclass of requests.Session for token management
d. URL Module (wqb_urls) – REST endpoint definitions
e. Parameter Builders (FilterRange, DateTimeRange)
f. Logger Factory (wqb_logger)
- Third-Party Libraries
- requests (HTTP)
- asyncio (concurrent coroutines)
- logging (configurable log sinks)
- External Service
- WorldQuant BRAIN REST API

##### Relationships and data flow
1. User code calls wqb.wqb_logger() and/or instantiates WQBSession(credentials, logger).
2. WQBSession (via AutoAuthSession) authenticates to BRAIN API once and stores the token.
3. User code invokes session methods (search_*, locate_*, filter_*, simulate, check, submit).
4. For each call:
– WQBSession uses wqb_urls to build the endpoint URL
– Parameter builders serialize filters into query strings or JSON bodies
– requests.Session (AutoAuthSession) sends HTTP requests (sync) or aiohttp/async wrappers (async)
– Responses returned as requests.Response or Iterable[Response] to the user
5. Concurrent methods (concurrent_simulate, concurrent_check) spawn asyncio tasks, gather responses.
6. Logging hooks capture request/response metadata, optionally persisted to console/file.

##### Architectural patterns & design principles
- Adapter/Facade: WQBSession wraps the low-level REST API into a uniform Python interface.
- Extension: AutoAuthSession extends requests.Session to transparently handle token refresh.
- Separation of Concerns: URL definitions, parameter building, session management, logging are modularized.
- Asynchronous Concurrency: expose both sync (generator) and async (coroutines) interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    UA["User Application"]:::user

    %% wqb Library Modules
    subgraph "wqb Python Library" 
        direction TB
        PA["Public API Layer"]:::internal
        WS["WQBSession (Facade)"]:::internal
        AAS["AutoAuthSession"]:::internal
        URLM["URL Definitions Module"]:::internal
        DTR["DateTimeRange"]:::internal
        FR["FilterRange"]:::internal
        LF["Logger Factory"]:::internal
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        direction TB
        REQ["requests"]:::third
        ASY["asyncio"]:::third
        LOGM["logging"]:::third
    end

    %% External Service
    BRAIN["WorldQuant BRAIN API"]:::external

    %% Connections - Sync flows
    UA -->|"calls methods"| PA
    PA -->|"instantiates"| WS
    WS -->|"uses sync session"| AAS
    AAS -->|"HTTP request"| BRAIN
    WS -->|"builds URLs"| URLM
    WS -->|"builds params"| DTR
    WS -->|"builds params"| FR
    WS -->|"logs via"| LOGM
    LOGM -->|"logs to console/file"| LF

    %% Connections - Async flows
    WS -.->|"spawns tasks"| ASY
    ASY -.->|"concurrent HTTP calls"| BRAIN

    %% Click Events
    click PA "https://github.com/rocky-d/wqb/blob/master/wqb/__init__.py"
    click LF "https://github.com/rocky-d/wqb/blob/master/wqb/__init__.py"
    click WS "https://github.com/rocky-d/wqb/blob/master/wqb/wqb_session.py"
    click AAS "https://github.com/rocky-d/wqb/blob/master/wqb/auto_auth_session.py"
    click URLM "https://github.com/rocky-d/wqb/blob/master/wqb/wqb_urls.py"
    click DTR "https://github.com/rocky-d/wqb/blob/master/wqb/datetime_range.py"
    click FR "https://github.com/rocky-d/wqb/blob/master/wqb/filter_range.py"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#2980B9,color:#1B2631;
    classDef third fill:#D5D8DC,stroke:#566573,color:#1B2631;
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#1B2631;
    classDef user fill:#D2B4DE,stroke:#6C3483,color:#1B2631;
```
