arbitrage-api/docs/ARCHITECTURE.md

Architecture

Overview

flowchart LR
  subgraph external [External]
    API[The Odds API]
  end

  subgraph repo [Repository]
    Fetch[odds/scripts/fetch_odds.py]
    Samples[(odds/data/samples/*.json)]
    Arb[Arbitrage engine - planned]
  end

  API --> Fetch --> Samples
  Samples --> Arb

Odds pipeline (current and planned)

Current

1. Operator sets ODDS_API_KEY in .env
2. fetch_odds.py calls GET /v4/sports/{sport_key}/odds
3. Response JSON is stored under odds/data/samples/

Planned

Stage	Responsibility
Loader	Read JSON snapshots or live API
Normalizer	One row per (event, bookmaker, market, outcome)
Arb scanner	Compare implied probabilities across books
Reporter	CLI or export of opportunities above margin threshold

Configuration

Variable	Used by	Description
ODDS_API_KEY	fetch_odds.py	The Odds API authentication
ODDS_REGIONS	(optional future)	Default regions for fetch
ODDS_MARKETS	(optional future)	Default markets for fetch

Dependencies

See root requirements.txt. Odds fetch uses requests.

Out of scope for git

• arb-venv/, .venv/ — local virtualenvs
• .env — secrets