feat: initial BetonBLK project structure

2026-03-21 07:19:34 -04:00
commit f70db389e2
5 changed files with 200 additions and 0 deletions
@@ -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)