JoeKnowsBall
JoeKnowsBall is a free sports-research web application for model-informed rankings, matchups, props, picks, fantasy analysis, and data-driven decision support. The repository contains the public React application, serverless API handlers, sports-data pipelines, model support code, and automated tests.
Product areas
- MLB game, home-run, strikeout, batter-versus-pitcher, power-ranking, and experimental research tools
- PGA tournament models, rankings, picks, best bets, history, and custom/DFS workflows
- NFL schedules, matchup analysis, power ratings, team guides, analytics, futures, and weekly command-center views
- Fantasy football rankings and points-allowed research
- NCAA basketball schedules, matchups, bracket, and betting-edge views
- College-football rankings, schedules, teams, matchups, and conference views
- World Cup, public-odds, and additional research experiences
Stack
- React 18, TypeScript, Vite, and React Router
- Tailwind CSS with Shadcn/ui and Radix component patterns
- TanStack React Query for client-side data orchestration
- Supabase integration and serverless handlers under
api/
- Vitest and Playwright for automated testing
Local setup
Requirements: Node.js and npm. The repository currently declares npm 10 in package.json.
npm ci
npm run dev
The Vite development server is configured on port 8080. Some connected features and data-generation scripts require service-specific environment variables; do not assume .env.example configures every integration.
Useful commands:
npm test
npm run lint
npm run build
See docs/TESTING.md before browser automation or pipeline-specific validation.
Repository layout
src/pages/ — route-level application viewssrc/components/ — shared and sport-specific React componentssrc/hooks/ — data-loading and orchestration hookssrc/lib/ — shared utilities, sports-domain logic, and model supportsrc/features/ — feature-owned application modulesapi/ — serverless API handlers and supporting server codescripts/ — ingestion, generation, validation, grading, and publishing toolsdata/ — source caches, research inputs, and generated analytical artifactspublic/data/ — browser-consumed data artifactstests/ and colocated *.test.* files — Playwright, Vitest, and script testsdocs/ — durable context plus historical feature, model, audit, and migration records
Generated-data warning
Most files under public/data/, data/generated/, and dist/ are produced by repository tooling. Consult the owning pipeline documentation before changing them.
Repository guidance
