# Architecture

## Overview

```mermaid
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