# 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 1. Apply migration 003 manually (blocked by DNS) 2. Install Python dependencies for evolution microservice 3. Set Stripe env vars and test payment flow end-to-end 4. Deploy frontend to Vercel 5. Begin Feature 4.1 (model learning loop)