Run any Skill in Manus with one click

heater-appb-architecture

Stars2

Forks0

UpdatedJuly 6, 2026 at 19:01

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

hicklax13

hicklax13/HEATER_v1.0.0

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

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).

More from this repository

same repository

heater-appb-auth-billing

hicklax13/HEATER_v1.0.0

Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.

2026-07-062

heater-appb-bubba-ai

hicklax13/HEATER_v1.0.0

Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.

2026-07-062

heater-appb-calibration-backtest

hicklax13/HEATER_v1.0.0

Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.

2026-07-062

heater-appb-contracts-openapi

hicklax13/HEATER_v1.0.0

Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.

2026-07-062

heater-appb-debugging

hicklax13/HEATER_v1.0.0

Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.

2026-07-062

heater-appb-deploy-ops

hicklax13/HEATER_v1.0.0

Use when deploying HEATER App B, changing Railway or Vercel env vars/service config, diagnosing live 502s/timeouts/blank data after deploy, operating the Yahoo-token or Statcast relays, or driving Railway/Vercel headlessly from a terminal.

2026-07-062

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

Request path

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

Boot & deploy

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)

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).