vyndr/DECISIONS.md

# BetonBLK — Architecture Decisions

## Format
Each decision follows this structure:
- DECISION-[NNN]: [Title]
- Date: [YYYY-MM-DD]
- Context: [Why this decision was needed]
- Decision: [What was decided]
- Alternatives considered: [What else was on the table]
- Consequences: [What this means going forward]

## Decisions
### DECISION-001: Odds API Raw Response Format (Feature 1.1)
- Date: 2026-03-21
- Context: Needed to verify actual Odds API response shape before writing normalizer. Made live test calls to `/v4/sports/basketball_nba/events` and `/v4/sports/basketball_nba/events/{id}/odds`.

**Raw response structure (verified):**
```
Event level:
  - id: "a1158df1a3a21def58491807df167c6a"
  - home_team: "Washington Wizards" (FULL NAME, not abbreviation)
  - away_team: "Oklahoma City Thunder"
  - commence_time: "2026-03-21T21:10:00Z" (ISO 8601 UTC)

Bookmaker level (nested under event.bookmakers[]):
  - key: "fanduel" | "draftkings" | "betmgm"
  - title: "FanDuel" | "DraftKings" (human-readable)

Market level (nested under bookmaker.markets[]):
  - key: "player_points" (matches our expected market keys)
  - last_update: "2026-03-21T12:17:04Z" (ISO 8601 UTC)

Outcome level (nested under market.outcomes[]):
  - name: "Over" | "Under"
  - description: "Shai Gilgeous-Alexander" (FULL PLAYER NAME)
  - price: -110 (American odds, integer)
  - point: 28.5 (the line)
```

**Key findings:**
1. Team names are full names ("Washington Wizards"), NOT 3-letter abbreviations. We need a mapping table.
2. Player names are in `description` field, full names.
3. Over/Under for the same player+line appear as separate outcome objects. Must pair them.
4. The API does NOT tell us which team a player belongs to. We only know home_team/away_team for the event. Player-to-team assignment requires roster data (Feature 1.2).
5. `markets` param accepts comma-separated values — can fetch all 8 prop markets in one API call per event.

**Quota headers (verified):**
- `x-requests-used`: cumulative credits used this month
- `x-requests-remaining`: credits left
- `x-requests-last`: credits consumed by this specific call (was 1)

- Decision:
  1. Build a static NBA team name → 3-letter abbreviation mapping in utils.
  2. Normalizer must pair Over/Under outcomes by player name + point value.
  3. For Feature 1.1, set `team` to the full team name from the event. Player-to-team resolution deferred to Feature 1.2 integration.
  4. Fetch all markets in a single call per event to conserve credits.
  5. Use on-demand fetching only (not polling) — fetch from API only when a user request hits and cache is cold.
- Alternatives considered:
  - Could skip team abbreviations entirely — rejected because downstream features (Prop Engine, UI) need short team identifiers.
  - Could try to resolve player→team via external lookup now — rejected because Feature 1.2 will provide this natively.
- Consequences:
  - Need `src/utils/teamMap.js` with full name → abbreviation mapping.
  - Normalizer groups Over+Under outcomes by `description` + `point`.
  - Credit budget: ~1 credit per event per refresh. With 15-min cache + on-demand only, budget stays within 500/month for typical usage.

### DECISION-002: Credit Conservation Strategy (Feature 1.1)
- Date: 2026-03-21
- Context: Starter plan = 500 credits/month. Player props require per-event API calls (sport-level endpoint only supports main markets). ~10 NBA games/day.
- Decision: On-demand fetching only. Never poll. Cache aggressively at 15-min TTL. Batch all markets into one call per event. For a full NBA slate, one refresh = ~10 credits. At 15-min cache, even heavy usage stays under budget.
- Alternatives considered: Background polling every 15 min — rejected, would burn ~480 credits per game day.
- Consequences: First request after cache expires will be slower (live API call). Acceptable tradeoff for free tier.

### DECISION-003: Python Microservice for nba_api (Feature 1.2)
- Date: 2026-03-21
- Context: nba_api is a Python library. Backend is Node.js/Express. Need a bridge.
- Decision: FastAPI microservice. Node calls it via internal HTTP. Python stays idiomatic, caching strategy (24hr season averages, 1hr recent games) lives in the Python service with its own Redis connection.
- Alternatives considered:
  - Python child process (Node spawns python3, parses stdout) — rejected: cold start on every call, awkward error handling.
  - Pre-fetch cron (Python writes to Redis on schedule, Node reads) — rejected: more moving parts, stale data risk.
- Consequences: Two processes to run (Node + Python). Need a startup script or docker-compose. Internal port convention: Node on 3000, Python on 8000.

### DECISION-004: Supabase Auth + RLS (Feature 1.4)
- Date: 2026-03-21
- Context: Need auth provider for user system. Supabase already in stack.
- Decision: Supabase Auth. RLS enabled at project level. Our `users` table extends `auth.users` via FK on `id`. All tables use RLS policies scoped to `auth.uid()`.
- Alternatives considered:
  - Clerk — better DX but adds a vendor, costs more at scale.
  - Auth-agnostic (own users table, plug in later) — rejected: delays RLS setup, more migration work later.
- Consequences: All table access goes through RLS. Service role key bypasses RLS for admin/backend operations. Anon key used for client-side auth flows.

### DECISION-005: Spreads Market Added to Odds API Fetch (Feature 1.3)
- Date: 2026-03-21
- Context: Feature 1.3 kill condition `blowout_risk` needs game point spread. The Odds API supports a `spreads` market alongside player props.
- Decision: Add `spreads` to the comma-separated markets list in the existing per-event API call. Zero additional API credits — the spreads data rides alongside the player prop data in the same request.
- Alternatives considered: Skip blowout_risk for now — rejected because it's a high-value kill condition that prevents bad bets on blowout games.
- Consequences: `oddsService.js` now returns a `spreads` array alongside `props`. The `extractSpreads()` function in `oddsNormalizer.js` parses game-level spread data separately from player-level props.

### DECISION-006: Auth via Supabase auth.getUser() (Feature 2.1)
- Date: 2026-03-21
- Context: Need to verify Supabase JWTs in the scan endpoint. Options were manual JWT verification with secret or using Supabase client.
- Decision: Use `supabase.auth.getUser(token)` from `@supabase/supabase-js`. Simpler, no JWT secret management, automatically validates token expiry and revocation.
- Alternatives considered: Manual JWT decode with `jsonwebtoken` library — rejected: more code, need to manage JWT secret, doesn't check revocation.
- Consequences: Auth middleware depends on Supabase API being reachable (same DNS blocker in WSL2). In production this is fine.

### DECISION-007: Atomic Scan Count Increment (Feature 2.1)
- Date: 2026-03-21
- Context: Race condition risk — two concurrent scans from same free-tier user could both read scan_count=4 and both proceed past the limit.
- Decision: Use atomic `UPDATE users SET scan_count = scan_count + 1 WHERE id = :id AND scan_count = :current_count RETURNING scan_count`. If no rows returned, another request incremented first.
- Alternatives considered: Postgres advisory locks — rejected: overkill for this use case. Optimistic concurrency with the WHERE clause is simpler and sufficient.
- Consequences: At worst, one of two concurrent requests will fail to increment and still proceed (the check happens before analysis). Acceptable for MVP — the 5-scan limit is soft, not a billing boundary.