# jebin1999/triangular-arbitrage-histotical-opportunities- architecture

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

- Interactive diagram: https://gitdiagram.com/jebin1999/triangular-arbitrage-histotical-opportunities-
- Repository: https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-

## Overview

##### Project Type and Purpose
- This is a standalone Python-based analytics tool (not a full-stack web app) whose sole purpose is to detect triangular arbitrage opportunities in the Forex market by:
- Fetching historical FX data from Yahoo Finance
- Calculating cross-rates and discrepancies
- Reporting opportunities in the terminal and optionally exporting to CSV

##### High-Level Architectural Components
a. External Data Source
- Yahoo Finance API (via the `yfinance` library)
b. Data Ingestion / Fetcher Module
- `fetch_historical_data()` pulls price histories for each currency pair
c. Data Alignment & Joining
- A transform step that merges the three time series into a single DataFrame indexed by date
d. Analysis / Arbitrage Engine
- `calculate_triangular_arbitrage()` applies the cross-rate formula
- Iterates through merged data in `list_past_arbitrage_opportunities()`
e. In-Memory Storage
- Pandas DataFrame (`stored_opportunities_df`) holding detected opportunities
f. Output / Export Module
- Terminal printout of results
- Optional export to `arbitrage_opportunities.csv`
g. (Future) Notification Service
- SMS/WhatsApp/Telegram hooks for real-time alerts

##### Architectural Patterns & Design Principles
- Pipeline / ETL-style flow: ingest → transform → analyze → output
- Single responsibility per module (fetch, transform, analyze, export)
- In-memory data handling with pandas for simplicity and performance
- Modular code organization enables easy extension (e.g., adding real-time fetching or alerts)

##### Technologies & Frameworks
- Python 3.x
- pandas (data manipulation and in-memory store)
- yfinance (external API wrapper)
- CSV file writing (built-in I/O)
- (Optional) notification libraries for SMS/WhatsApp/Telegram

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    YF["Yahoo Finance API"]:::external

    %% Processing Modules
    Fetcher["fetch_historical_data()"]:::process
    Transformer["Data Alignment & Joining"]:::process
    Analyzer["calculate_triangular_arbitrage() / list_past_arbitrage_opportunities()"]:::process
    Exporter["Export Module"]:::process

    %% Storage / Output
    StorageDF(("stored_opportunities_df DataFrame")):::storage
    Console["Console Output"]:::storage
    ExportCSV(("arbitrage_opportunities.csv")):::storage

    %% Future Component
    Notification["Notification Service (Future)"]:::future

    %% Data Flow
    YF -->|"raw rates"| Fetcher
    Fetcher -->|"Raw DataFrames"| Transformer
    Transformer -->|"Merged DataFrame"| Analyzer
    Analyzer -->|"opportunity records"| StorageDF
    Analyzer -->|"print results"| Console
    Analyzer -->|"send to export"| Exporter
    Exporter -->|"write CSV"| ExportCSV
    Analyzer -->|"real-time alert (future)"| Notification

    %% Click Events
    click YF "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"
    click Fetcher "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"
    click Transformer "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"
    click Analyzer "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"
    click StorageDF "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"
    click Exporter "https://github.com/jebin1999/triangular-arbitrage-histotical-opportunities-/blob/main/TriangularArbitrageHistoricalExchange.ipynb"

    %% Styles
    classDef external fill:#adebeb,stroke:#333,stroke-width:1px
    classDef process fill:#cafad3,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef future fill:#d3d3d3,stroke:#333,stroke-width:1px
```
