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, historical dataset refresh
Web app	`sflow-app/`	React app for Predictions, Results, Strategies, Account
CLI/MCP	`sflow-cli/`	Terminal and assistant tool access, included with every subscription
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 page visualization payloads
`products/{sport}/...`	Historical dataset refresh CSVs and coverage sidecars

Firestore stores customers, API keys, subscription state, historical dataset 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 Product

Product	Backend behavior
Scottfree Sports AI	Web app, REST API (200,000 monthly requests at up to 50 req/s), CLI/MCP, and historical dataset refresh (8/month for datasets purchased separately) — all included in the single `ai` tier.

Legacy subscribers on the retired Sports Data / Sports Basic / Sports Premium products keep working under a legacy-alias classification that grants the same ai-tier access.

CLI And MCP

The scottfree-sports-cli package is included with every Scottfree Sports AI subscription.

Entrypoints:

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

The MCP server exposes 17 public customer data tools for subscriber 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 quota:

Plan	Limit	Rate
Scottfree Sports AI	200,000 requests	50 requests/second

Historical dataset 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 Product #

CLI And MCP #

Scheduled Jobs #

Auth And Rate Limits #

Current Product Stance #