# alpacahq/alpaca-py architecture

> Architecture diagram of the GitHub repository alpacahq/alpaca-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alpacahq/alpaca-py
- Repository: https://github.com/alpacahq/alpaca-py

## Overview

##### Main Components Identification

The system should be divided into three main API service components:
- Broker API Services
- Trading API Services
- Market Data API Services

##### Detailed Architecture Breakdown

a) Core Components Layer:
- Common Module (/alpaca/common/)
- REST client base
- Utilities
- Constants
- Base models
- Exception handling

b) API Service Layers:

##### Broker API Layer (/alpaca/broker/)
- Client interface
- Account management
- Trading operations
- Funding operations
- Document management

##### Trading API Layer (/alpaca/trading/)
- Trading client
- Order management
- Tracking
- Account operations
- Streaming capabilities

##### Market Data API Layer (/alpaca/data/)
- Historical data clients
- Stocks
- Crypto
- Options
- News
- Live data streams
- Data models
- Screener functionality

##### Component Relationships

Key interactions:
**External Alpaca APIs**
- ↕
**Common Layer (Base Infrastructure)**
- ↕
- ┌─────────────────────┐
- ↓         ↓          ↓
**Broker    Trading    Market Data**
- API       API         API
- ↓         ↓          ↓
**Client Applications/Users**

##### Additional Details

Important elements:
- WebSocket connections for real-time data
- REST API endpoints
- Data validation layer (Pydantic)
- Authentication flow
- Model relationships

##### Implementation Notes

- The modular design allowing independent use of different APIs
- The shared common infrastructure
- Data validation and type checking
- Asynchronous capabilities for streaming data
- Clear separation between historical and live data services

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External["External Alpaca APIs"]
        direction TB
        AlpacaAPI[("Alpaca API Endpoints")]:::external
    end

    subgraph Core["Core Components Layer"]
        direction TB
        RestBase["REST Client Base"]:::core
        Utils["Utilities"]:::core
        Constants["Constants"]:::core
        BaseModels["Base Models"]:::core
        Exceptions["Exception Handling"]:::core

        click RestBase "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/common/rest.py"
        click Utils "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/common/utils.py"
        click Constants "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/common/constants.py"
        click BaseModels "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/common/models.py"
        click Exceptions "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/common/exceptions.py"
    end

    subgraph BrokerAPI["Broker API Layer"]
        direction TB
        BrokerClient["Client Interface"]:::broker
        AccountMgmt["Account Management"]:::broker
        TradingOps["Trading Operations"]:::broker
        FundingOps["Funding Operations"]:::broker
        DocMgmt["Document Management"]:::broker

        click BrokerClient "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/broker/client.py"
        click AccountMgmt "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/broker/models/accounts.py"
        click TradingOps "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/broker/models/trading.py"
        click FundingOps "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/broker/models/funding.py"
        click DocMgmt "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/broker/models/documents.py"
    end

    subgraph TradingAPI["Trading API Layer"]
        direction TB
        TradingClient["Trading Client"]:::trading
        OrderMgmt["Order Management"]:::trading
        PositionTrack["Position Tracking"]:::trading
        StreamCap["Streaming Capabilities"]:::trading

        click TradingClient "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/trading/client.py"
        click OrderMgmt "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/trading/models.py"
        click StreamCap "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/trading/stream.py"
    end

    subgraph MarketData["Market Data API Layer"]
        direction TB
        subgraph Historical["Historical Data"]
            direction TB
            StockHist["Stocks"]:::market
            CryptoHist["Crypto"]:::market
            OptionsHist["Options"]:::market
            NewsHist["News"]:::market

            click StockHist "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/historical/stock.py"
            click CryptoHist "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/historical/crypto.py"
            click OptionsHist "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/historical/option.py"
            click NewsHist "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/historical/news.py"
        end

        subgraph LiveData["Live Data"]
            direction TB
            WebSocket["WebSocket Base"]:::market
            StockLive["Live Stocks"]:::market
            CryptoLive["Live Crypto"]:::market
            OptionsLive["Live Options"]:::market

            click WebSocket "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/live/websocket.py"
            click StockLive "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/live/stock.py"
            click CryptoLive "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/live/crypto.py"
            click OptionsLive "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/live/option.py"
        end

        subgraph DataModels["Data Models"]
            direction TB
            Bars["Bars"]:::market
            Quotes["Quotes"]:::market
            Trades["Trades"]:::market
            Screener["Screener"]:::market

            click Bars "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/models/bars.py"
            click Quotes "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/models/quotes.py"
            click Trades "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/models/trades.py"
            click Screener "https://github.com/alpacahq/alpaca-py/blob/master/alpaca/data/models/screener.py"
        end
    end

    %% Connections
    AlpacaAPI --> Core
    Core --> BrokerAPI
    Core --> TradingAPI
    Core --> MarketData

    %% Styles
    classDef external fill:#gray,stroke:#333,stroke-width:2px
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef broker fill:#2ecc71,stroke:#27ae60,color:white
    classDef trading fill:#e67e22,stroke:#d35400,color:white
    classDef market fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        direction TB
        L1["External Services"]:::external
        L2["Core Components"]:::core
        L3["Broker API"]:::broker
        L4["Trading API"]:::trading
        L5["Market Data API"]:::market
    end
```
