# jmfernandes/robin_stocks architecture

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

- Interactive diagram: https://gitdiagram.com/jmfernandes/robin_stocks
- Repository: https://github.com/jmfernandes/robin_stocks

## Overview

##### Project Type and Purpose
- This is an open-source Python SDK (client library) that wraps three external trading APIs: Robinhood, Gemini, and TD Ameritrade.
- Users (scripts, Jupyter notebooks, production code) import this package to perform authentication, fetch market data, place orders, etc., via simple Python calls.

##### High-Level File/Module Structure
- Top-level:
- setup.py, requirements.txt, CI/CD config (.github/workflows/pythonapp.yml), docs/ (Sphinx sources), examples/, tests/, .test.env.
- Core package: robin_stocks/
- Subpackages: robin_stocks/robinhood, robin_stocks/gemini, robin_stocks/tda
- Each subpackage contains modules for authentication, account, markets, orders, helper utilities, globals, URLs.

##### Key README Insights
- Emphasis on three supported APIs, usage examples, testing via pytest + pytest-dotenv, publishing to PyPI.
- No internal database or UI—pure client wrapper.

##### Components
a. User/Application Layer
- Scripts or applications that import robin_stocks.<api_module>
- Example code (examples/ directory)
b. SDK Core Layer
- Authentication module (session management, 2FA, token handling)
- API-specific modules (account, markets, orders, crypto, options, etc.)
- Helper/Globals (shared utilities, endpoint definitions)
- Packaging/Setup (setup.py, versioning)
c. External Services
- Robinhood REST API endpoints
- Gemini REST API endpoints
- TD Ameritrade REST API endpoints
d. Support Infrastructure
- Testing: pytest, test files hitting sandbox endpoints (tests/)
- CI/CD: GitHub Actions (pythonapp.yml) running lint, tests, publish
- Docs: Sphinx (docs/source → HTML) published to ReadTheDocs

##### Relationship and Data Flow
- Authentication flow:
User code calls auth module → SDK manages credentials from .env → obtains tokens → attaches to subsequent requests
- CI/CD flow: on push → GitHub Actions → run tests, build docs, publish package

##### Architectural Patterns & Design Principles
- Modular separation by API (robinhood, gemini, tda)
- Layered approach: Authentication → Core actions (orders/markets) → Helpers/Globals
- Single responsibility per module.
- Environment-driven configuration (.test.env / .env).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Application Layer
    User["User Application / Scripts"]:::user
    Examples["Examples (robinhood/gemini/tda)"]:::user

    %% SDK Core
    subgraph "SDK Core"
        subgraph "Robinhood Module"
            AuthRH["authentication.py"]:::sdk
            AccountRH["account.py"]:::sdk
            MarketsRH["markets.py"]:::sdk
            OrdersRH["orders.py"]:::sdk
            OptionsRH["options.py"]:::sdk
            CryptoRH["crypto.py"]:::sdk
            ProfilesRH["profiles.py"]:::sdk
            StocksRH["stocks.py"]:::sdk
            ExportRH["export.py"]:::sdk
            HelperRH["helper.py"]:::sdk
            GlobalsRH["globals.py"]:::sdk
            URLsRH["urls.py"]:::sdk
        end
        subgraph "Gemini Module"
            AuthG["authentication.py"]:::sdk
            AccountG["account.py"]:::sdk
            CryptoG["crypto.py"]:::sdk
            OrdersG["orders.py"]:::sdk
            HelperG["helper.py"]:::sdk
            GlobalsG["globals.py"]:::sdk
            URLsG["urls.py"]:::sdk
        end
        subgraph "TDA Module"
            AuthT["authentication.py"]:::sdk
            AccountsT["accounts.py"]:::sdk
            MarketsT["markets.py"]:::sdk
            OrdersT["orders.py"]:::sdk
            StocksT["stocks.py"]:::sdk
            HelperT["helper.py"]:::sdk
            GlobalsT["globals.py"]:::sdk
            URLsT["urls.py"]:::sdk
        end
        subgraph "Packaging & Config"
            Setup["setup.py"]:::config
            Req["requirements.txt"]:::config
            Manifest["MANIFEST.in"]:::config
            Env[".test.env / .env"]:::config
        end
    end

    %% External Services
    subgraph "External APIs"
        RobinAPI["Robinhood REST API"]:::external
        GeminiAPI["Gemini REST API"]:::external
        TDAAPI["TD Ameritrade REST API"]:::external
    end

    %% Support Infrastructure
    subgraph "Support Infrastructure"
        subgraph "Testing"
            TestRH["test_robinhood.py"]:::infra
            TestG["test_gemini.py"]:::infra
            TestT["test_tda.py"]:::infra
            PytestIni["pytest.ini"]:::infra
            TestEnv[".test.env"]:::infra
        end
        CI["GitHub Actions"]:::infra
        subgraph "Docs (Sphinx)"
            DocConf["conf.py"]:::infra
            DocIndex["index.rst"]:::infra
            DocRH["robinhood.rst"]:::infra
            DocG["gemini.rst"]:::infra
            DocT["tda.rst"]:::infra
        end
        ReadTheDocs["ReadTheDocs"]:::infra
        PyPI["PyPI"]:::external
    end

    %% Data Flows
    User -->|imports| Examples
    Examples -->|calls| AuthRH
    Examples -->|calls| AuthG
    Examples -->|calls| AuthT

    AuthRH -->|HTTP via requests| RobinAPI
    AccountRH -->|HTTP via requests| RobinAPI
    MarketsRH -->|HTTP via requests| RobinAPI
    OrdersRH -->|HTTP via requests| RobinAPI
    OptionsRH -->|HTTP via requests| RobinAPI
    CryptoRH -->|HTTP via requests| RobinAPI
    ProfilesRH -->|HTTP via requests| RobinAPI
    StocksRH -->|HTTP via requests| RobinAPI
    ExportRH -->|HTTP via requests| RobinAPI

    AuthG -->|HTTP via requests| GeminiAPI
    AccountG -->|HTTP via requests| GeminiAPI
    CryptoG -->|HTTP via requests| GeminiAPI
    OrdersG -->|HTTP via requests| GeminiAPI

    AuthT -->|HTTP via requests| TDAAPI
    AccountsT -->|HTTP via requests| TDAAPI
    MarketsT -->|HTTP via requests| TDAAPI
    OrdersT -->|HTTP via requests| TDAAPI
    StocksT -->|HTTP via requests| TDAAPI

    %% Helpers and Globals usage
    AuthRH --> HelperRH
    AccountRH --> HelperRH
    MarketsRH --> HelperRH
    AuthG --> HelperG
    AccountG --> HelperG
    AuthT --> HelperT
    AccountsT --> HelperT

    AuthRH --> GlobalsRH
    AuthG --> GlobalsG
    AuthT --> GlobalsT

    %% CI/CD Flow
    CI -->|run tests| TestRH
    CI -->|run tests| TestG
    CI -->|run tests| TestT
    CI -->|use config| PytestIni
    CI -->|use env| TestEnv
    CI -->|build docs| DocConf
    CI -->|build docs| DocIndex
    CI -->|build docs| DocRH
    CI -->|build docs| DocG
    CI -->|build docs| DocT
    DocConf -->|publish| ReadTheDocs
    DocIndex -->|publish| ReadTheDocs
    ReadTheDocs --> ReadTheDocs
    CI -->|publish package| PyPI
    Setup -->|package| PyPI
    Req -->|dependencies| Setup
    Manifest -->|includes files| Setup

    %% Click Events
    click Examples "https://github.com/jmfernandes/robin_stocks/tree/master/examples/robinhood"
    click AuthRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/authentication.py"
    click AccountRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/account.py"
    click MarketsRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/markets.py"
    click OrdersRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/orders.py"
    click OptionsRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/options.py"
    click CryptoRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/crypto.py"
    click ProfilesRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/profiles.py"
    click StocksRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/stocks.py"
    click ExportRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/export.py"
    click HelperRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/helper.py"
    click GlobalsRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/globals.py"
    click URLsRH "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/robinhood/urls.py"

    click AuthG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/authentication.py"
    click AccountG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/account.py"
    click CryptoG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/crypto.py"
    click OrdersG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/orders.py"
    click HelperG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/helper.py"
    click GlobalsG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/globals.py"
    click URLsG "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/gemini/urls.py"

    click AuthT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/authentication.py"
    click AccountsT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/accounts.py"
    click MarketsT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/markets.py"
    click OrdersT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/orders.py"
    click StocksT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/stocks.py"
    click HelperT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/helper.py"
    click GlobalsT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/globals.py"
    click URLsT "https://github.com/jmfernandes/robin_stocks/blob/master/robin_stocks/tda/urls.py"

    click Setup "https://github.com/jmfernandes/robin_stocks/blob/master/setup.py"
    click Req "https://github.com/jmfernandes/robin_stocks/blob/master/requirements.txt"
    click Manifest "https://github.com/jmfernandes/robin_stocks/blob/master/MANIFEST.in"
    click Env "https://github.com/jmfernandes/robin_stocks/blob/master/.test.env"

    click TestRH "https://github.com/jmfernandes/robin_stocks/blob/master/tests/test_robinhood.py"
    click TestG "https://github.com/jmfernandes/robin_stocks/blob/master/tests/test_gemini.py"
    click TestT "https://github.com/jmfernandes/robin_stocks/blob/master/tests/test_tda.py"
    click PytestIni "https://github.com/jmfernandes/robin_stocks/blob/master/pytest.ini"
    click TestEnv "https://github.com/jmfernandes/robin_stocks/blob/master/.test.env"

    click CI "https://github.com/jmfernandes/robin_stocks/blob/master/.github/workflows/pythonapp.yml"

    click DocConf "https://github.com/jmfernandes/robin_stocks/blob/master/docs/source/conf.py"
    click DocIndex "https://github.com/jmfernandes/robin_stocks/blob/master/docs/source/index.rst"
    click DocRH "https://github.com/jmfernandes/robin_stocks/blob/master/docs/source/robinhood.rst"
    click DocG "https://github.com/jmfernandes/robin_stocks/blob/master/docs/source/gemini.rst"
    click DocT "https://github.com/jmfernandes/robin_stocks/blob/master/docs/source/tda.rst"

    %% Styles
    classDef user fill:#eeeeee,stroke:#666666;
    classDef sdk fill:#cce5ff,stroke:#0000ff;
    classDef external fill:#c8e6c9,stroke:#006400;
    classDef infra fill:#ffe0b2,stroke:#e65100;
    classDef config fill:#f0f0f0,stroke:#888888;
```
