heater-appb-architecture

name	heater-appb-architecture
description	Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.

HEATER App B — System Model

Repo: C:\Users\conno\Code\HEATER_v1.0.1 (GitHub name stays HEATER_v1.0.0). App B is the product: Next.js 16 on Vercel + FastAPI on Railway over shared, UNCHANGED Python engines in src/. App A (Streamlit, app.py + pages/) is a frozen strangler-fig fallback — never build there; it constrains App B only via frozen-reference equivalence tests on shared engines.

Request path

Browser → Vercel Next server → server-side rewrite /api/:path* → ${HEATER_API_BASE}/api/:path* (next.config.ts:3-13) → Railway FastAPI (api/main.py::create_app factory, ~line 31) → thin router (api/routers/) → service (api/services/*_service.py, the ONLY layer importing src/) → engines → SQLite.

CORS is moot. The proxy makes every browser call same-origin. HEATER_API_CORS_ORIGINS need not be set in prod; don't "fix" CORS for browser traffic.

The two databases — never cross them

DB	Env	Owner	Contents
data/draft_tool.db	HEATER_DB_PATH	scheduler is sole writer; API reads	players, projections, rosters, stats — everything engines read
data/api_state.db	HEATER_API_DB_PATH	API stores (api/stores/)	api_users, api_subscriptions, api_saved_prompts, api_leagues, api_memberships, api_processed_events

Auth/billing/tenancy state goes in api_state.db via a store (Protocol + InMemory + Sqlite pattern). Writing user state into draft_tool.db, or engine data into api_state.db, is a design violation. Single Railway replica is a hard invariant (in-process writer + SQLite; railway.api.toml numReplicas 1).

Boot & deploy

start-api.sh: seeds Yahoo token on first boot, backgrounds the scheduler loop (HEATER_SCHEDULER_BOOT=1, HEATER_SCHEDULER_IS_OWNER=1), then exec python -m uvicorn api.main:create_app --factory --port $PORT. It is a factory — local runs need uvicorn api.main:create_app --factory --port 8000. Push to master auto-deploys App B; each deploy re-bootstraps data (~10 min) before projections/pool are warm. Healthcheck /healthz; also /livez + /readyz (api/health.py).

Dormancy predicates (features are built + OFF until env set)

Predicate	Env	Flips on
clerk_configured() api/auth.py:166	CLERK_ISSUER	real auth + 401 read-gate (require_login, require_viewer_context)
billing_env_configured() api/billing_config.py:13	STRIPE_SECRET_KEY and STRIPE_PRO_PRICE_ID	require_pro 402 gate + tier AI caps
relay_enabled() src/token_relay.py:49	HEATER_TOKEN_RELAY_URL + HEATER_RELAY_KEY	Yahoo token pulls
statcast relay gate src/statcast_relay.py:60	HEATER_STATCAST_RELAY_URL	Savant xwOBA/barrel upserts

On the live beta, Clerk is ON and Stripe is intentionally UNSET (friends are free). Absent Stripe env is not a bug.

Failure story (why config-file discipline matters)

2026-06-22: App B 502'd (Railway serviceDomain targetPort 8000 vs 8080) and was running Streamlit, not FastAPI — the service built the root Dockerfile until the Railway service setting railwayConfigFile=railway.api.toml pointed it at api/Dockerfile + start-api.sh. Rule: App B's build is defined by railway.api.toml; the root Dockerfile/railway.toml belong to App A.

Non-negotiables

• src/ engines stay byte-identical for the live Streamlit app — add behavior in services or NEW src/ modules (see heater-appb-engine-composition).
• Everything additive + env-dormant; never activate owner-gated infra (Postgres/B2.2+, Clerk prod keys, Stripe live) without explicit owner go.
• Yahoo write scope (fspt-w) is externally unavailable — HEATER is a read-only advisor; live writes 401 by design.

When NOT to use

Streamlit/App A page work (out of scope by decree); pure engine math questions (heater-appb-engine-composition); deep deploy ops (heater-appb-deploy-ops).