feat: initial BetonBLK project structure
This commit is contained in:
Executable
+19
@@ -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
|
||||||
Executable
+21
@@ -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]
|
||||||
@@ -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)
|
||||||
Executable
+13
@@ -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.]
|
||||||
Executable
+84
@@ -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
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user