# alpacahq/example-hftish architecture

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

- Interactive diagram: https://gitdiagram.com/alpacahq/example-hftish
- Repository: https://github.com/alpacahq/example-hftish

## Overview

##### Main Components
- Trading Algorithm (tick_taker.py): This is the heart of the system where the logic for detecting bid/ask spread moves and executing trades is implemented.
- External Market Data Stream: Represents the incoming live market data from the Polygon streaming API that drives the algorithm.
- Trading API Integration: Represents the connection to Alpaca’s API that the script uses to execute trades. Both paper (testing) and live execution endpoints (or switching based on environment variables) should be highlighted.
- Environment & Configuration Setup: This includes the use of environment variables (APCA_API_KEY_ID, APCA_API_SECRET_KEY, and optionally the APCA_API_BASE_URL) which are part of the configuration process.

##### Relationships and Interactions
- The Trading Algorithm continuously listens to real-time market data from the Market Data Stream component.
- It processes this data to detect slight movements in the bid/ask spread.
- Once a trading signal is generated, the algorithm sends orders via the Trading API Integration component.
- The environment variables and command-line parameters (such as --symbol, --quantity, etc.) are used to configure the algorithm at startup.

##### Architectural Patterns and Principles
- The system follows a streaming-based approach for real-time data processing.
- The design leverages external services (Alpaca and Polygon) for data and trade execution, which means handling external dependencies, rate limits, and reliability are part of the overall system responsibilities.

##### Relevant Technologies
- Python 3.6+: The base language.
- Alpaca Trading API SDK: For order sending and account management.
- Polygon Streaming API: For receiving streaming market data.
- Pipenv: For dependency and environment management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    EE["Configuration (env variables, CLI) (README.md)"]:::config
    PSAPI["Polygon Streaming API"]:::external

    subgraph "Internal Trading Algorithm"
        TT["Trading Algorithm (tick_taker.py)"]:::internal
        MDH["Market Data Handler"]:::internal
        SG["Signal Generator"]:::internal
        OE["Order Executor"]:::internal
        TT -->|"processes"| MDH
        MDH -->|"generates"| SG
        SG -->|"sends_order"| OE
    end

    AAPI["Alpaca Trading API"]:::external

    subgraph "Dependency Management"
        DEP1["Pipfile"]:::dependency
        DEP2["Pipfile.lock"]:::dependency
    end

    PSAPI -->|"market_data"| TT
    OE -->|"trade_order"| AAPI
    EE -->|"configures"| TT
    DEP1 -->|"dependency"| TT
    DEP2 -->|"dependency"| TT

    click TT "https://github.com/alpacahq/example-hftish/blob/master/tick_taker.py"
    click DEP1 "https://github.com/alpacahq/example-hftish/tree/master/Pipfile"
    click DEP2 "https://github.com/alpacahq/example-hftish/blob/master/Pipfile.lock"
    click EE "https://github.com/alpacahq/example-hftish/blob/master/README.md"

    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef dependency fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
