From f70db389e2196a82ef0072c4b0baf93ea9b92315 Mon Sep 17 00:00:00 2001
From: Kev <kevdevelops@gmail.com>
Date: Sat, 21 Mar 2026 07:19:34 -0400
Subject: [PATCH] feat: initial BetonBLK project structure

---
 BLOCKERS.md    | 19 ++++++++++++
 BUILD-STATE.md | 21 +++++++++++++
 CLAUDE.md      | 63 +++++++++++++++++++++++++++++++++++++
 DECISIONS.md   | 13 ++++++++
 ROADMAP.md     | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 200 insertions(+)
 create mode 100755 BLOCKERS.md
 create mode 100755 BUILD-STATE.md
 create mode 100755 CLAUDE.md
 create mode 100755 DECISIONS.md
 create mode 100755 ROADMAP.md

diff --git a/BLOCKERS.md b/BLOCKERS.md
new file mode 100755
index 0000000..8943489
--- /dev/null
+++ b/BLOCKERS.md
@@ -0,0 +1,19 @@
+# BetonBLK — Blockers
+
+## BLOCKER-001: Hosting Decision
+**Status:** OPEN
+**Impact:** Blocks deployment (Phase 3)
+**Options:**
+- Vercel — free tier, great for Next.js, limited backend
+- Railway — better for full-stack, Node.js native, $5/mo start
+**Decision needed by:** End of Phase 1
+**Owner:** Kev
+
+## BLOCKER-002: Auth Provider
+**Status:** OPEN
+**Impact:** Blocks user system (Feature 1.4+)
+**Options:**
+- Clerk — better DX, faster setup, more expensive at scale
+- Supabase Auth — already in stack, free tier generous, slightly more setup
+**Decision needed by:** Before Feature 1.4 implementation
+**Owner:** Kev
diff --git a/BUILD-STATE.md b/BUILD-STATE.md
new file mode 100755
index 0000000..98b5982
--- /dev/null
+++ b/BUILD-STATE.md
@@ -0,0 +1,21 @@
+# BetonBLK — Build State
+
+## Last Updated
+[Not yet started]
+
+## Current Phase
+Phase 1 — Foundation
+
+## What Has Shipped
+Nothing yet. Project initialized.
+
+## What's Next
+Feature 1.1 — Odds API Integration (no dependencies)
+Feature 1.2 — NBA_API Stats Wrapper (no dependencies, can build parallel)
+Feature 1.4 — Database Schema (no dependencies, can build parallel)
+
+## Active Blockers
+See BLOCKERS.md
+
+## Session Log
+[No sessions yet]
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100755
index 0000000..26b1a39
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,63 @@
+# BetonBLK — Claude Code Project Context
+
+## What This Is
+Sports betting intelligence SaaS. Real software product.
+Three tiers: Free (5 scans), Analyst ($19.99 / $14.99 founder), Desk ($49.99 / $34.99 founder).
+
+## Tech Stack
+- Backend: Node.js / Express
+- Database: Supabase (PostgreSQL)
+- Frontend: React Native (built in Cursor)
+- Data: The Odds API ($30/mo), nba_api (free, Python wrapper)
+- Caching: Redis — 15min for odds, 24hr for season averages, 1hr for recent games
+- Payments: Stripe
+
+## Critical Rules — Non-Negotiable
+
+### 1. NO CODE WITHOUT A SPEC
+Every feature requires a spec file in `specs/` before any code is written.
+Spec must include: endpoints, data shapes, acceptance criteria, test plan.
+Get approval before building.
+
+### 2. WSL2 HEREDOC RULE
+WSL2 corrupts heredoc for files over 10 lines.
+ALWAYS use Python file-writing: `python3` with triple-quoted strings.
+This applies to every file creation operation.
+
+### 3. 5 QUALITY GATES (all must pass before any feature is marked complete)
+1. Unit tests pass
+2. Integration tests pass
+3. Acceptance criteria met (from spec)
+4. PR description written
+5. CLAUDE.md updated if anything new learned
+
+### 4. BUILD-STATE.md
+Update after every session. What shipped, what's next, any blockers.
+
+### 5. BLOCKERS.md
+If you hit something you cannot resolve: log it. Don't guess. Don't skip.
+
+## Folder Structure
+```
+betonblk/
+├── src/
+│   ├── routes/        # Express route handlers
+│   ├── models/        # Supabase data models
+│   ├── services/      # Business logic (prop analysis, odds normalization)
+│   ├── middleware/     # Auth, rate limiting, scan counting
+│   └── utils/         # Helpers, formatters, validators
+├── tests/             # Unit + integration tests
+├── docs/              # API docs, architecture notes
+├── specs/             # Feature specs (write BEFORE code)
+├── build-briefs/      # Session summaries
+├── CLAUDE.md          # This file
+├── ROADMAP.md         # Feature roadmap with phases
+├── BUILD-STATE.md     # Current build status
+├── BLOCKERS.md        # Unresolved blockers
+└── DECISIONS.md       # Architecture decisions log
+```
+
+## Active Skills
+- betonblk-voice (all user-facing output)
+- prop-analysis (grading methodology)
+- monetization-system (scan-5 pitch, tier conversion)
diff --git a/DECISIONS.md b/DECISIONS.md
new file mode 100755
index 0000000..a8c336b
--- /dev/null
+++ b/DECISIONS.md
@@ -0,0 +1,13 @@
+# 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
+[No decisions logged yet. First entries expected: hosting + auth provider.]
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100755
index 0000000..d759044
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,84 @@
+# BetonBLK — Product Roadmap
+
+## PHASE 1 — FOUNDATION (Weeks 1-2)
+
+### Feature 1.1 — Odds API Integration (no dependencies — build first)
+- GET /api/odds/nba — Returns today's NBA props normalized across DraftKings, FanDuel, BetMGM
+- GET /api/odds/ncaab — NCAA props in season
+- Data shape: { player, team, stat_type, line, over_odds, under_odds, book, timestamp }
+- Cache: 15-minute refresh. Graceful fallback if rate limit hit.
+- Tests: Mock API response, verify normalization, verify cache behavior
+- Status: NOT STARTED
+
+### Feature 1.2 — NBA_API Stats Wrapper (no dependencies — build parallel with 1.1)
+- getPlayerSeasonAvg(playerId, statType) → season average
+- getPlayerLast10Avg(playerId, statType) → last 10 game average
+- getPlayerSplits(playerId, statType, filters) → home/away/B2B/vs opponent situational
+- Cache: 24hr on season averages, 1hr on recent games
+- Status: NOT STARTED
+
+### Feature 1.3 — Prop Analysis Engine (depends: 1.1 + 1.2)
+- Input: { player, stat_type, line, book }
+- Step 1-6: Season avg compare → situational factors → injury check → kill conditions → grade A/B/C/D → BetonBLK voice format
+- Output: { grade, edge_pct, reasoning, kill_conditions_triggered, confidence }
+- Status: NOT STARTED
+
+### Feature 1.4 — Database Schema — Supabase (no dependencies)
+- users: id, email, tier, scan_count, scan_reset_date, stripe_customer_id
+- picks: id, user_id, player, stat, line, grade, reasoning, created_at
+- outcomes: id, pick_id, result, actual_value, logged_at
+- bets: id, user_id, amount, slip_data, book, placed_at
+- performance: id, user_id, roi, win_rate, sample_size, period
+- scan_sessions: id, user_id, legs[], final_grade, kill_conditions, created_at
+- Status: NOT STARTED
+
+### Feature 1.5 — Bet Submission (3 Methods) (depends: 1.4)
+- Screenshot: POST /api/bets/screenshot — image upload, OCR extracts bet data
+- Quick slip: POST /api/bets/quickslip — natural language: 'Jokic PRA 50.5 over $20 DraftKings'
+- Sportsbook sync: POST /api/bets/sync — OAuth, auto-logs all bets
+- Status: NOT STARTED
+
+## PHASE 2 — CORE PRODUCT (Weeks 3-4)
+Depends on: Phase 1 complete
+
+### Feature 2.1 — Parlay Scan (depends: 1.3 + 1.4)
+- Logic: Grade each leg → check correlation → grade overall parlay
+- Scan cap: Check scan_count before processing. If 5: return personalized upgrade pitch
+- Status: NOT STARTED
+
+### Feature 2.2 — Real-Time Line Movement + Cascade Detection (depends: 1.1)
+- Line movement: Alert when line moves 0.5+ points from 8 AM baseline. Flag sharp money direction.
+- Cascade: Star player scratches → identify affected props → re-grade → alert affected users
+- Status: NOT STARTED
+
+## PHASE 3 — WEB MVP (Weeks 5-6)
+Depends on: Phase 2 complete
+
+### Feature 3.1 — Landing Page (no code dependencies)
+- Next.js. Hero, How It Works, 3-tier pricing with founder badge, email CTA
+- Status: NOT STARTED
+
+### Feature 3.2 — Scan UI (depends: 2.1)
+- Natural language input or manual leg builder
+- Color-coded grades. Scan counter.
+- Status: NOT STARTED
+
+### Feature 3.3 — Bet Tracker UI (depends: 1.5)
+- Win rate, ROI, behavioral pattern card at 30+ bets
+- Status: NOT STARTED
+
+### Feature 3.4 — Stripe Integration (depends: 1.4)
+- Checkout → subscription → webhook → tier update in DB
+- Founder code locks rate
+- Status: NOT STARTED
+
+## DEPENDENCY MAP
+```
+1.1 (Odds API) ──┐
+                  ├──→ 1.3 (Prop Engine) ──→ 2.1 (Parlay Scan) ──→ 3.2 (Scan UI)
+1.2 (NBA API) ───┘
+1.1 ──→ 2.2 (Line Movement + Cascade)
+1.4 (DB Schema) ──→ 1.5 (Bet Submission) ──→ 3.3 (Bet Tracker)
+1.4 ──→ 3.4 (Stripe)
+3.1 (Landing Page) — no code dependencies
+```