Initial commit: Arbitrage

docs/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# 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