# areed1192/python-trading-robot architecture

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

- Interactive diagram: https://gitdiagram.com/areed1192/python-trading-robot
- Repository: https://github.com/areed1192/python-trading-robot

## Overview

##### Project type and purpose
- This is a Python library (“Python Trading Robot”) that provides a set of abstractions and utilities for building algorithmic trading bots against the TD Ameritrade API.
- Its main responsibilities are:
- Managing authentication and session state with the broker’s API
- Streaming and storing real-time and historical market data
- Computing technical indicators
- Modeling a portfolio and computing risk metrics
- Defining and executing complex order types (with take-profit, stop-loss, etc.)

##### File structure
- Top-level:
- `.github/`, `LICENSE`, CI workflows → project maintenance & continuous analysis
- `config/` → configuration template & helper for writing config files
- `pyrobot/` → core library package
- `data/` → sample data responses (for testing or offline simulations)
- `samples/` → example scripts showing how to use the library
- `tests/` → unit tests for each major module
- `setup.py` → packaging metadata and dependencies
- Inside `pyrobot/` you have clearly separated modules:
- `robot.py` → orchestrator, authentication, API session management
- `stock_frame.py` → in-memory data store for ticks & history
- `indicators.py` → indicator definitions and updating logic
- `portfolio.py` → portfolio state and risk-metric calculations
- `trades.py` & `order_status.py` → trade-object model and order status retrieval

##### README for additional insights
- Confirms core objects: `PyRobot` (the main entry point), `Portfolio`, `Trade`, `StockFrame`, `Indicator`
- Describes TD Ameritrade credentials & state persistence to a JSON file on disk
- Sample usage is entirely programmatic—no web UI or database

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Client Application (Sample Scripts)"
        direction TB
        CA1["trading_robot.py"]:::client
        CA2["trading_robot_indicators.py"]:::client
        CA3["trading_robot_indicators_compare.py"]:::client
    end

    %% PyRobot Library
    subgraph "PyRobot Library"
        direction TB
        PY1["Authentication & Session Manager\n(robot.py)"]:::lib
        PY2["Market Data Store\n(stock_frame.py)"]:::lib
        PY3["Indicator Engine\n(indicators.py)"]:::lib
        PY4["Portfolio Manager\n(portfolio.py)"]:::lib
        PY5["Order Construction & Execution\n(trades.py)"]:::lib
        PY6["Order Status Monitor\n(order_status.py)"]:::lib
    end

    %% Local Storage & Config
    subgraph "Local Configuration & State Store"
        direction TB
        CFG1["config.ini"]:::storage
        CFG2["write_config.py"]:::storage
    end

    %% External Service
    EXT1["TD Ameritrade API\n(REST/WebSocket)"]:::external

    %% Test & CI
    subgraph "Test Harness & Sample Data"    
        direction TB
        TSD["Sample Data (data/*.jsonc)"]:::test
        TSR["Sample API Responses\n(samples/responses/*.jsonc)"]:::test
        UT["Unit Tests (tests/*.py)"]:::test
    end

    %% Connections
    CA1 -->|"uses"| PY1
    CA2 -->|"uses"| PY1
    CA3 -->|"uses"| PY1

    PY1 -->|"reads/writes"| CFG1
    PY1 -->|"reads/writes"| CFG2

    PY1 -->|"REST/WS calls"| EXT1
    PY5 -->|"sends NewOrder"| EXT1
    PY6 -->|"polls/listens"| EXT1

    EXT1 -->|"market data"| PY2
    PY2 -->|"feeds"| PY3
    PY2 -->|"feeds"| PY4

    PY3 -->|"indicators data"| PY4
    PY4 -->|"risk metrics"| CA1

    %% Test connections
    TSD -->|"offline data"| PY2
    TSR -->|"mock API responses"| PY1
    UT -->|"tests modules"| PY1
    UT -->|"tests modules"| PY2
    UT -->|"tests modules"| PY3
    UT -->|"tests modules"| PY4
    UT -->|"tests modules"| PY5

    %% Click Events
    click CA1 "https://github.com/areed1192/python-trading-robot/blob/master/samples/trading_robot.py"
    click CA2 "https://github.com/areed1192/python-trading-robot/blob/master/samples/trading_robot_indicators.py"
    click CA3 "https://github.com/areed1192/python-trading-robot/blob/master/samples/trading_robot_indicators_compare.py"
    click PY1 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/robot.py"
    click PY2 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/stock_frame.py"
    click PY3 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/indicators.py"
    click PY4 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/portfolio.py"
    click PY5 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/trades.py"
    click PY6 "https://github.com/areed1192/python-trading-robot/blob/master/pyrobot/order_status.py"
    click CFG1 "https://github.com/areed1192/python-trading-robot/blob/master/config/config.ini"
    click CFG2 "https://github.com/areed1192/python-trading-robot/blob/master/config/write_config.py"
    click TSD "https://github.com/areed1192/python-trading-robot/blob/master/data/*.jsonc"
    click TSR "https://github.com/areed1192/python-trading-robot/blob/master/samples/responses/*.jsonc"
    click UT "https://github.com/areed1192/python-trading-robot/blob/master/tests/test_robot.py"

    %% Styles
    classDef client fill:#d9edf7,stroke:#31708f,color:#31708f
    classDef lib fill:#cce5ff,stroke:#004085,color:#004085
    classDef storage fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef test fill:#f8f9fa,stroke-dasharray: 5 5,stroke:#6c757d,color:#6c757d
```
