Architecture

Scottfree Sports is a data pipeline, API, web app, CLI, and MCP tool surface for sports model research.

High-Level Flow

text

Odds/results sources
  -> game-score files in GCS
  -> product and model pipelines
  -> prediction/result/summary artifacts in GCS
  -> FastAPI on Cloud Run
  -> web app, REST API, CLI, MCP

Core Components

Component	Location	Purpose
Odds and game data pipeline	`code/`	Updates canonical game-score files and repairs provider gaps
Model pipeline	`code/`, `sflow/`	Generates prediction, result, summary, rolling, density, and team-form artifacts
Product pipeline	`Products/`, `code/pipeline_product_daily.py`	Generates customer CSV snapshots and product release packages
API backend	`api/`	FastAPI service, auth, rate limits, customer account, Sports Data refresh
Web app	`sflow-app/`	React app for Predictions, Results, Summary, Account
CLI/MCP	`sflow-cli/`	Premium terminal and assistant tool access
Documentation	`docs/`	VitePress docs site

Data Storage

Primary storage is Google Cloud Storage bucket alphapy-sports.

Important object groups:

Group	Purpose
`{SPORT}/{sport}_game_scores_1g.csv`	Canonical source game-score tape per sport
Prediction artifacts	Current slate model probabilities
Live result artifacts	Recent graded model results
Summary artifacts	Model performance summaries
Rolling/density artifacts	Results and Summary page visualization payloads
`products/{sport}/...`	Sports Data refresh CSVs and coverage sidecars

Firestore stores customers, API keys, subscription state, Sports Data ownership, usage counters, and operational audit records.

API Backend

Production API:

text

https://sports-api.scottfreellc.com

Main route groups:

Path family	Purpose
`/api/v1/predictions/{sport}/{model_type}`	Current slate predictions
`/api/v1/public/ml-picks/{sport}/{market}`	Free website ML table feed
`/api/v1/odds/{sport}`	Current odds
`/api/v1/results/{sport}/{model_type}`	Recent graded results
`/api/v1/results/{sport}/{model_type}/rolling`	Rolling results visualization payload
`/api/v1/results/{sport}/{model_type}/density`	Result distribution payload
`/api/v1/results/{sport}/{model_type}/team-form`	Current-season team form
`/api/v1/summary/{sport}/{model_type}`	Model summary
`/api/v1/customers/me`	Account
`/api/v1/scottfree-sports-data/*`	Historical dataset refreshes

Legacy /picks/* and /edge-picks/* endpoints return empty compatibility payloads because no validated betting selector is active.

Customer Products

Product	Backend behavior
Sports Data	Account plus historical dataset refresh endpoints. Prediction API quota is zero unless the same customer also has Basic/Premium.
Sports Basic	Web app and REST API with 50,000 monthly requests.
Sports Premium	Basic plus CLI/MCP with 200,000 monthly requests.

CLI And MCP

The Premium package is scottfree-sports-cli.

Entrypoints:

Command	Purpose
`sfs`	CLI
`sfs-mcp`	MCP server

The MCP server exposes 16 public customer data tools for Premium assistant workflows.

Scheduled Jobs

Job	Purpose
`pipeline-game-odds`	Refresh game files and repair recent source gaps
`pipeline-models`	Generate predictions/results/summary artifacts
`pipeline-product-daily`	Generate product CSV snapshots
`pipeline-orders-poll`	Poll SquareSpace orders and reconcile customers

Auth And Rate Limits

API keys can be sent by:

X-API-Key
Authorization: Bearer
api_key query parameter for quick tests

Monthly API quotas:

Plan	Limit
Basic	50,000
Premium	200,000

Sports Data refresh quota is separate: 8 refreshes per calendar month.

Current Product Stance

Scottfree Sports exposes model research, market-implied probabilities, line fields, current odds, results, summaries, and contextual data. It does not currently market or activate a validated betting selector, line-movement pick system, Kelly sizing system, or guaranteed profitable pick feed.

Architecture #

High-Level Flow #

Core Components #

Data Storage #

API Backend #

Customer Products #

CLI And MCP #

Scheduled Jobs #

Auth And Rate Limits #

Current Product Stance #