From Victory

A daily-discipline, mental-toughness, and Christian faith app for athletes ages 13 and up (calibrated for 13-25) — live for hockey, basketball, golf, football, baseball, lacrosse, and soccer. Parents buy for athletes under 18; adults 18+ can own their own account (self-serve, flag-gated — not yet enabled in production). Identity precedes performance: we operate from Christ's victory, not toward it (Hebrews 12:1-2).

See CLAUDE.md for full mission, scope, and non-negotiable constraints (minor data protection, journal safety, content voice).

Tech stack

• Frontend: Next.js 14 (App Router), Tailwind CSS, TypeScript strict
• Mobile delivery: PWA (primary). Capacitor native shells in apps/native are an additive App Store / Play path around the same web app — scaffolding only; store listings are not live. See docs/native-capacitor.md.
• Backend: Supabase (Postgres + Auth + Storage)
• Payments: Stripe Billing
• Hosting: Vercel (auto-deploy from main)

Repo layout

from-victory/
├── apps/web/             # Next.js app (Vercel)
├── apps/native/          # Capacitor Android + iOS shell (store distribution)
├── supabase/             # Migrations
└── .github/              # CI gates (build, typecheck, lint, audio-cache-bust, privacy-verdict)

Prerequisites

• Node.js 20+ for the app — build, dev, test (see .nvmrc)
• Node.js 22.6+ only for the dev-time audio:* and scripts:* tooling, which executes .ts files directly via node --experimental-strip-types (added in Node 22.6). The deployed app and CI still run on Node 20+; this requirement applies to local audio generation / script export only.
• npm 10+ (ships with Node 20)

Setup

git clone <repo-url> from-victory
cd from-victory
nvm use            # optional, picks up .nvmrc
npm install
cp apps/web/.env.example apps/web/.env.local
# Edit .env.local and fill in Supabase + Stripe values (see comments in the file).

Start the local Supabase stack (Supabase CLI required):

supabase start                    # starts local Postgres, Auth, Studio
supabase db push                  # apply all migrations
supabase gen types typescript --local > apps/web/lib/supabase/database.types.ts

Production migrations are applied automatically: merging a PR that touches supabase/migrations/** triggers the db-migrate workflow, which runs supabase db push against the linked project (FV-259 — closes the code-ahead-of-schema gap that caused the 2026-06-12 login outage). It needs the SUPABASE_ACCESS_TOKEN and SUPABASE_DB_PASSWORD repo secrets; if they are missing the job fails loudly and the push must be run manually. Regenerating types (supabase gen types --linked) remains a manual follow-up.

A daily drift detector backstops both halves of the deploy (FV-188 — infra-drift workflow, scheduled + workflow_dispatch). It is strictly read-only — it never applies migrations or changes secrets — and emails KC through the existing Resend alert channel (ALERT_EMAIL_TO) when it finds a gap: (1) any local supabase/migrations/** file missing on the linked project, or (2) any required env var from apps/web/.env.example absent in the GitHub production environment. The env check reports by name only and never reads, logs, or emails a value. Mark a var optional with a # fv-env-check: optional comment above it in .env.example. Required secrets/config for the job are documented at the top of .github/workflows/infra-drift.yml. The two checks run locally too:

# from apps/web/
node --experimental-strip-types scripts/check-env-presence.ts --no-alert
supabase migration list --linked \
  | node --experimental-strip-types scripts/check-migration-drift.ts \
      --migrations-dir ../../supabase/migrations

For local Stripe webhook testing (Stripe CLI required):

stripe listen --forward-to localhost:3000/api/webhooks/stripe
# Copy the printed whsec_... value into STRIPE_WEBHOOK_SECRET in .env.local

For end-to-end tests:

cp apps/web/.env.test.example apps/web/.env.test
# Fill in the test credentials before running npm run test:e2e

Common commands

Run from the repo root:

Command	What it does
npm run dev	Start the Next.js dev server on :3000
npm run build	Production build of the web app
npm run typecheck	Run tsc --noEmit against apps/web
npm run lint	Run next lint
npm test	Run tests across workspaces (when present)

Native shells (Capacitor)

The web app stays on Vercel. apps/native wraps the hosted production URL in a Capacitor WebView for Play / App Store distribution. It does not replace the PWA and must not add tracking SDKs.

cd apps/native
npx cap sync
npm run build:android:debug    # needs Android SDK; see docs/native-capacitor.md
# iOS archive requires macOS + Xcode — see docs/ios-app-store-release.md

Application / bundle id is locked: com.fromvictoryapp.app (Play Console). Play enrollment, signing, Internal testing, and Data safety: docs/android-play-release.md. iOS / App Store (TestFlight-first; enrollment not started): docs/ios-app-store-release.md. Architecture + privacy rules: docs/native-capacitor.md.

Workflow rules

These are non-negotiable. See CLAUDE.md for the full version.

1. Never edit main directly. Branch off with feature/<name> or hotfix/<name>.
2. Commit in small logical units. Conventional commits: feat:, fix:, chore:, test:, docs:.
3. Every change goes through a PR. Merge through the GitHub UI.
4. CI must pass before merge — build, typecheck, tests, privacy-verdict status check.

Child safety

This product serves minors (13-17). Journal entries are athlete-only readable, enforced at the database level via Supabase RLS. The parent dashboard reads metadata only. No third-party analytics or ad SDKs on minor accounts, ever (California AADC / GDPR-K compliance floor). Every PR touching user data, auth, journal, migrations, or third-party SDKs is reviewed by the kids-privacy-officer subagent; the privacy-verdict required CI check enforces an explicit VERDICT: APPROVED before merge.

If you're contributing: read the relevant sections of CLAUDE.md before opening a PR.