8.1 KiB
8.1 KiB
ARCHITECTURE.md — VYNDR v1.0
Section 1: The Mission
VYNDR is a bet on advancement. Sports betting intelligence SaaS built to reverse the flow of a multi-trillion dollar industry.
Three tiers:
- Free — 5 scans
- Analyst — $19.99/mo ($14.99 founder price)
- Desk — $49.99/mo ($34.99 founder price)
The house has data scientists. We give everyone else the same firepower.
Section 2: What Was Already Built (Phase 0)
11 features shipped. 237 tests passing.
Phase 1 — Core Engine
- Odds API integration — live odds ingestion from The Odds API
- NBA stats wrapper — Python FastAPI microservice wrapping nba_api
- Prop analysis engine — 6-step grading pipeline (season avg, recent form, situational, line comparison, kill conditions, grade)
- Database schema — 9 tables with row-level security
- Bet submission — 3 methods (manual, scan-to-save, quick pick)
Phase 2 — Intelligence Layer
- Parlay scan — correlation detection across 5 types, monetization hooks
- Line movement + cascade detection — baseline capture, movement alerts, scratch-and-regrade
Phase 3 — User-Facing Product
- Landing page — Next.js with Tailwind, cyan design system
- Scan UI — mobile-first prop scanning interface
- Bet tracker — portfolio-style bet management
- Stripe integration — checkout, webhooks, portal, founder code system
Stack
- Backend: Node.js / Express
- Database: Supabase (PostgreSQL) with RLS on all tables
- Frontend: Next.js, Tailwind CSS, cyan design system
- Caching: Redis — 15min odds, 24hr season averages, 1hr recent games
- Payments: Stripe
- Data: The Odds API ($30/mo), nba_api (free, Python wrapper)
Section 3: Phase 1 Additions (Current Session)
12 additions built in a single session:
| # | Addition | What It Does |
|---|---|---|
| 1 | Founder's Note | Immutable constant, tested for integrity |
| 2 | Mission Header | X-VYNDR-Mission on all API responses |
| 3 | Stats Endpoints | /api/stats/parlays-graded, /api/stats/public, /api/props/live |
| 4 | Dynamic Role Profile System | 8 functional roles, Shannon entropy variance, conditional profiles, lineup profiles |
| 5 | Player Selector | 4-step mobile-first flow (placeholder — frontend handled by Cowork) |
| 6 | Parlay Probability | Per-leg probability, combined, phi coefficient correlation, juice-adjusted EV |
| 7 | MLB Prop Grading | 14 stat types, 10 kill conditions, 30 park coordinates, weather API |
| 8 | Intelligence Engine | Similarity, evolution/PELT, line discrepancy, alt line scanner, Bayesian, model trainer |
| 9 | Lineup Watch Speed | Role activation detection, 60-second alert window |
| 10 | Design System Update | Forest green variables, DemoScan result card, Hero tagline, live props strip |
| 11 | Accuracy Ledger + Marketplace | /ledger page and /marketplace page |
| 12 | Architecture Documentation | This file |
Section 4: All Services and Data Flow
Backend Services
Odds + Data Ingestion
- oddsService.js — fetches from Odds API, caches in Redis (15min TTL)
- nbaStatsClient.js — Python FastAPI wrapper for NBA season/game stats
- mlbStatsClient.js — MLB Stats API wrapper
Grading Pipeline
- propAnalyzer.js — 6-step grading pipeline (season avg, recent form, situational, line comparison, kill conditions, grade)
- grader.js — composite score to grade (A/B/C/D) with confidence
- killConditions.js — 6 NBA kill conditions
- mlbGrader.js — MLB-specific grading with adjusted thresholds
- mlbKillConditions.js — 10 MLB kill conditions + weather API integration
Parlay + Correlation
- correlationEngine.js — parlay correlation detection (5 correlation types)
- parlayGrader.js — parlay-level grading derived from leg grades
- parlayScanService.js — orchestrates full scan flow
- correlationMath.js — phi coefficient calculation, EV computation
Line Intelligence
- lineMovementService.js — baseline capture + movement detection
- cascadeService.js — scratch detection + regrade triggers
- alertService.js — cascade alert management
- lineDiscrepancyDetector.js — sharp vs square book gap detection
- altLineScanner.js — optimal alternate line finding
Role + Profile System
- roleProfileEngine.js — role distribution calculation, elevation detection
- roleStabilityEngine.js — stability scoring with decay
Advanced Intelligence
- similarityEngine.js — 10-factor game similarity matching
- evolutionEngine.js — Node wrapper for Python PELT microservice
- bayesianEngine.js — correct distribution shape per stat type
- modelTrainer.js — walk-forward validation, CLV tracking, drift detection
Payments
- stripeService.js — checkout sessions, webhooks, customer portal, founder codes
Python Microservices
| Service | Framework | Port | Purpose |
|---|---|---|---|
| NBA stats wrapper | FastAPI | 8000 | nba_api Python wrapper |
| Evolution engine | Flask | 5001 | PELT changepoint detection via ruptures |
Data Flow
Odds API
|
v
oddsService.js --> Redis Cache (15min TTL)
|
v
propAnalyzer.js
|-- nbaStatsClient.js --> FastAPI (port 8000) --> nba_api
|-- mlbStatsClient.js --> MLB Stats API
|-- roleProfileEngine.js
|-- similarityEngine.js
|-- bayesianEngine.js
|
v
grader.js / mlbGrader.js
|-- killConditions.js / mlbKillConditions.js
|
v
parlayScanService.js
|-- correlationEngine.js
|-- parlayGrader.js
|-- correlationMath.js (phi, EV)
|
v
Supabase (PostgreSQL)
|
v
lineMovementService.js --> cascadeService.js --> alertService.js
Section 5: Database Schema
Original Tables (Migrations 001, 002)
- users — auth, tier, founder status
- picks — individual prop picks with grades
- scan_sessions — scan history per user
- cascade_alerts — line movement alert records
- line_baselines — captured opening lines
- line_movements — detected line changes
- Plus standard auth tables (managed by Supabase)
New Tables (Migration 003)
- player_role_profiles — per-player role distribution snapshots
- lineup_role_profiles — team lineup composition profiles
- player_role_activations — role elevation/change events
- model_predictions_extended — predictions with confidence and methodology
- prediction_registry — pre-registered predictions (public read, service write)
- joint_outcomes — correlated outcome tracking for phi coefficient
- discrepancy_reliability_scores — sharp/square gap reliability history
All tables enforce row-level security (RLS). The prediction_registry table has public read access and service-role-only write access.
Section 6: Phase 2 Pending
- Model learning loop — Feature 4.1 spec exists in specs/
- Player selector UI completion — Cowork handles the design implementation
- Full parlay probability UI integration — connect backend math to scan results
- Real-time lineup watch CRON — scheduled job for role activation monitoring
- Evolution watch UI on ledger page — visualize PELT changepoints
- Pre-registered predictions system activation — public ledger goes live
- Physical ledger fulfillment — printed accuracy reports for Desk tier
- Education library content — betting strategy guides
Section 7: Known Gaps and Next Actions
Active Blockers
- BLOCKER-003: WSL2 DNS cannot resolve *.supabase.co — migration 003 must be applied manually via Supabase dashboard or a machine with direct DNS
Environment Dependencies
- Python evolution microservice requires ruptures + numpy installed
- Seed script requires NBA API network access to populate role profiles
- Stripe environment variables (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET) must be set
- Vercel deployment pending for Next.js frontend
Next Actions
- Apply migration 003 manually (blocked by DNS)
- Install Python dependencies for evolution microservice
- Set Stripe env vars and test payment flow end-to-end
- Deploy frontend to Vercel
- Begin Feature 4.1 (model learning loop)