⚠️ CR Priority (CR wins over all other sources):

• [CHR-6] adds zip_code (VARCHAR, nullable) to Users table + new country_zip_requirements reference table; GET /system/status returns zip_requirements map.
• [CHR-16] overrides RFQ V7 §3.3 (Pass Rate Aggregator cron) — cached_pass_rate is now computed via SUM(sims_passed)/(SUM(sims_passed)+SUM(sims_failed)) from the append-only Firm_Sim_Funnel_Snapshots table, populated daily by Zapier Flow 29 → POST /financial/daily-snap (no custom Node.js cron job needed).

UC Index

Step 0: System Initialization & Access Gates

UC_2.1.1 — System Status API

1. Overview

2. Trigger

The user navigates to the dedicated checkout page URL for the first time in the session.

Note: Checkout is implemented as a dedicated page, not a modal or overlay on the marketing page. Four architectural requirements govern this decision: (1) Same-Tab Routing (2) Cart Abandonment Deep Link (3) Attention Ratio — once inside the checkout funnel, all off-page distractions are removed. (4) No Standard Marketing Header/Footer — the standard marketing header and footer are not rendered on this route, except for Gate 1 (Waitlist, Ref: UC_2.1.3): when triggered, the checkout page is unmounted and the user is redirected to a separate dedicated Waitlist page, which does render the standard Marketing Header and Footer.

3. Pre-conditions

• User is on the checkout page.
• No prior GET /system/status response exists in the current session.

4. Post-conditions

• The full response payload (JSON below) is stored in the global checkout state.
• Gate 1 and Gate 2 conditions are evaluated immediately.

Response Payload Schema:

{
  "Global_Var_Allow_New_Signups": boolean,
  "is_founder_cohort":    boolean,
  "pricing_tiers": {        // object — keyed by product_id
    "EVAL_L1":            float,  // raw price, no currency symbol (e.g. 650.00)
    "EVAL_L2":            float,
    "EVAL_L5":            float
  },
  "geo_blocked":          boolean,
  "geo_country":          string,
  "geo_region":           string,
  "required_flow":        string,
  "methods": [
    {
      "id":               string,
      "label":            string,
      "explanatory_text": string,
      "cta_text":         string,
      "icon_tags":        [string]
    }
  ],
  "is_launch_phase":      boolean,
  "historical_pass_rate": float,
  "zip_requirements": {     // object — keyed by country_iso2, built from country_zip_requirements table
    "US":                 boolean,
    "CA":                 boolean,
    "IE":                 boolean
    // ... one entry per country in country_zip_requirements
  }
}

Note: current_price (float) and founder_count (int) have been removed from this response.

Field Notes:

country_zip_requirements Table Schema:

Seed data source: The initial dataset for this table can be sourced from standard ISO 3166-1 postal code requirement datasets publicly available on GitHub or via services such as GeoNames, rather than manually compiled per country.

methods[] detail — rendered at Step 6 (Payment Method selection):

5. Basic Flow

1. User navigates to the checkout page.
2. Frontend sends GET /system/status (Cloudflare headers CF-IPCountry, CF-Region are included automatically).
3. Backend processes, in order:

   • Step 3a — Geo-IP Gate: Extracts geo-IP from CF-IPCountry / CF-Region. Queries Compliance_geo_restrictions.

     • If match → sets geo_blocked = true and returns the payload immediately (skips Steps 3b–3e). Frontend then renders Gate 2 (UC_2.1.4) and stops — no further checkout UI is rendered.
     • If no match → continues to Step 3b.

     Table: Compliance_geo_restrictions

     Column	Type	Notes
     id	UUID (PK)
     country	VARCHAR	ISO 3166-1 alpha-2 or standard string
     region	VARCHAR	'All' = entire country blockedspecific subdivision = only that region blocked.Query logic: WHERE country = CF-IPCountry AND (region = 'All' OR region = CF-Region) — either row matching triggers the block.
     banned_reason	VARCHAR	Regulatory framework or policy justification
     created_at	TIMESTAMP
     updated_at	TIMESTAMP

   • Step 3b - Waitlist Gate: Reads Global_Var_Allow_New_Signups from Zapier Table C.

     • If Global_Var_Allow_New_Signups == FALSE -> backend returns the payload immediately (skips Steps 3c-3f). Frontend redirects (client-side navigation, same tab) to the dedicated Waitlist page (UC_2.1.3). Checkout UI is unmounted — no further checkout UI rendered.
     • If Global_Var_Allow_New_Signups == TRUE -> continues to Step 3c.

   • Step 3c — UI Routing: Queries checkout_ui_routing for a row matching geo_country (+ geo_region where applicable).

     • If match → sets required_flow to that row's value (e.g. FLOW_B, FLOW_C).
     • If no match → defaults required_flow = 'FLOW_A' (Override Model — see UC_2.1.2 §3 Routing Table).
     • Table: checkout_ui_routing

     Column	Type	Notes
     id	UUID (PK)
     country	VARCHAR	ISO 3166-1 standard name
     region	VARCHAR	'All' = applies to entire country (default)specific subdivision = overrides the 'All' row for that region only.Match logic (in order):(1) row where country = user_country AND region = user_region → use that required_flow;(2) else row where country = user_country AND region = 'All' → use that required_flow;(3) else → default FLOW_A.
     required_flow	VARCHAR	e.g.'Flow B', 'Flow C'
     justification	VARCHAR	Internal reference
     created_at	TIMESTAMP
     updated_at	TIMESTAMP

   • Step 3d — Gateway Filtering & Localization: Queries Payment_Method_Config twice and merges results into one methods array:

     • Rows where target_country = 'GLOBAL' AND is_active = TRUE → payment methods offered to every country (CC, Apple Pay, Google Pay, Crypto). GLOBAL is a literal value stored in the table, not a computed default.
     • Rows where target_country = geo_country AND is_active = TRUE → country-specific rails (e.g. target_country = 'ZA' → Dusupay Mobile Money/Bank).
     • Backend exclusion rule: if geo_country == 'IN', remove CC, APPLE_PAY, and GOOGLE_PAY from the merged array. India users receive only Crypto (Triple-A).

     Table: Payment_Method_Config

     Column	Type	Notes
     id	UUID (PK)
     target_country	String	'BR', 'CO', 'MX', 'PH', 'SG', 'JP', 'IN', 'ZA', 'KE', 'GB', 'FR', 'PL', 'NL', 'GLOBAL', 'AE'
     method_id	String	'CC', 'CRYPTO', 'APPLE_PAY', 'GOOGLE_PAY', 'DUSUPAY', 'T365'
     gateway_router	String	'NMI', 'TRIPLE_A', 'DUSUPAY', 'T365'
     label	String
     explanatory_text	String
     cta_text	String	Action button text (e.g.'Complete Purchase'). Max 25 characters — enforced at both DB constraint level (VARCHAR(25)) and API validation.
     icon_tags	[String]	Icon keys for frontend asset mapping
     is_active	Boolean	Ops toggle per row

   • Step 3e — Cohort & Pricing Check: Fetches is_founder_cohort (= Global_Var_Founder_Cohort_Open) from Zapier Table C — pricing switch only:

     • is_founder_cohort == TRUE → build pricing_tiers from the Founder Price column (Table J) for EVAL_L1, EVAL_L2, EVAL_L5.
     • is_founder_cohort == FALSE → build pricing_tiers from the Challenge Price column (Table J) for EVAL_L1, EVAL_L2, EVAL_L5.

     Table: Zapier Table C (Global Variables) — flat key-value config, not a row-based DB table.

     Variable	Value	Description
     Global_Var_Allow_New_Signups	boolean	Master Throttling Switch — read atStep 3b (Waitlist Gate).TRUE → checkout proceeds.FALSE → backend returns immediately. User is redirected to the dedicated Waitlist page.
     Global_Var_Founder_Cohort_Open	boolean	Master Cohort switch — read atStep 3e.TRUE → Founder pricing.FALSE → Standard pricing.

   • Step 3f — Launch Phase & Pass Rate (consumed by UC_2.1.2 Flow B and Flow C):- Reads system_launch_date from Platform_Configuration (row id = 1).

     • Sets is_launch_phase = TRUE if CurrentDate <= system_launch_date + 90 days, else FALSE.
     • Reads the cached_pass_rate column and returns it in the response as historical_pass_rate (rename only, same value — no re-calculation here; the value is pre-computed daily, see note below).
     • Used by Flow B (UK/Australia) and Flow C (EU/EEA) for the pass-rate disclosure at Step 5 — all other flows ignore them.

     Two separate mechanisms are involved:

     • Mechanism 1 — Zapier Flow 29 (write-only): runs daily at 5:05 PM EST (5 min after market close) and fires a webhook to POST /financial/daily-snap. Each run counts the number of users who transitioned to 'PASSED' or 'FAILED' status that day, and appends one new row to the Firm_Sim_Funnel_Snapshots table (columns sims_passed, sims_failed) - see schema below. Existing rows are never updated or deleted (append-only historical ledger). This mechanism never touches Platform_Configuration.
     • Mechanism 2 — Backend cron "Pass Rate Aggregator" (query corrected): a separate Node.js cron job, still required in the backend. Corrected formula: cached_pass_rate = SUM(sims_passed) / (SUM(sims_passed) + SUM(sims_failed)), computed across all rows of Firm_Sim_Funnel_Snapshots. Writes the resulting float back to Platform_Configuration (row id = 1, column cached_pass_rate). This avoids recalculating the ratio on every /system/status call.

     Table: Platform_Configuration — single-row global config, avoids aggregate queries on every checkout page load.

     Column	Type	Notes
     id	Integer (PK)	Locked to1
     system_launch_date	Date
     cached_pass_rate	Float

     Firm_Sim_Funnel_Snapshots

     Column	Type	Notes
     id	PK
     day	Date, Indexed
     time	Time	Informational — exact timestamp the daily job ran.
     conversions_new	Integer	New sim payments processed that day.
     conversions_resets	Integer	Sim reset payments processed that day.
     active_sims	Integer	Total users currently in an active sim state.
     sims_passed	Integer	Total users who successfully cleared the challenge that day.
     sims_failed	Integer	Total users who hit liquidation that day.
     pass_percent	Decimal	Per-day value:sims_passed / (sims_passed + sims_failed). Not the same as cumulative cached_pass_rate above.
     avg_pass_fail_duration	Decimal	Average days elapsed from sim start to pass/fail.

4. Backend returns JSON response (only reached if Step 3a did not trigger an early return due to geo_blocked = true).
5. Frontend stores full response in global checkout state.

6. Exceptional Flow

• [If GET /system/status fails — network error or timeout]

  • Ref: TE-SYS-01. Checkout UI is not rendered. User may retry once network is restored.

• [If GET /system/status fails — 5xx server error]

  • Ref: FP-03. Full-page error screen replaces checkout UI.

• [If geo headers are missing, empty, or return "XX"]

  • Backend defaults to geo_country = 'US', required_flow = 'FLOW_A'. User is NOT blocked.

• [If checkout_ui_routing query returns 0 rows]

  • Backend defaults to required_flow = 'FLOW_A'. User is NOT blocked.

7. Business Rules

BR_2.1.1.1: Single Call Per Session

GET /system/status is called exactly once when the checkout page first loads. Step navigation between Steps 1–5 does NOT trigger a new call. A full page refresh (F5) triggers a new call to re-hydrate global checkout state (pricing, geo, flow routing, etc.) — this does NOT mean the user's in-progress step/data is discarded; see BR_2.1.1.3 for the per-step reload/recovery behavior.

BR_2.1.1.2: Response Persistence

The full API response payload is stored in global checkout state. All subsequent steps read from this cached state — no re-fetching.

BR_2.1.1.3: Checkout Routing & Session Recovery Matrix (All Steps)

URL Structure: The checkout flow utilizes query parameters on a single path to define the current step (e.g. /checkout?step=selectassetclass, /checkout?step=payment). This enables deep-linking and cart-abandonment recovery (Klaviyo) to drop the user at their exact abandonment point.

Table 1 — Trigger: Page Reload (F5)

Table 2 — Trigger: URL Link Click (Deep-Link)

Table 3 — Trigger: Back from Marketing Page (Exit)

• If local browser storage still has the in-progress cart state: frontend restores it, and the next click on the [Checkout] button re-opens the checkout overlay directly at the step the user was on when they left — not back at Step 1. If that step is Step 6, the same direct-routing logic as Table 1 applies.
• If local storage is unavailable (cache cleared, new device): the checkout overlay restarts from Step 1, and the user re-types their email at Step 5 — including fields already captured before (name, billing address, etc.) — Step 5 displays the corresponding message.

BR_2.1.1.4: UTM Capture — Global, Root Layout (per CR-12)

The frontend reads current UTM values (utm_source, utm_medium, utm_campaign, utm_term, utm_content) from localStorage (written by the CR-12 root-layout script, not re-parsed from the URL at Step 0). This applies on every branch — including when the Waitlist Gate (UC_2.1.3, Step 3b) intercepts the flow — so email + UTM can still be attached to the direct API payload sent to ActiveCampaign/Klaviyo.

Attribution rule — last-touch, NOT first-seen wins: If the URL at any page load/route change contains UTM params, the root-layout script overwrites the existing localStorage values (last-touch attribution). If the URL has no UTM params, localStorage is left untouched (not cleared, not nulled).

All downstream consumers read the current localStorage value at the moment of their own action (not a value cached once at Step 0): Step 5 (UC_2.6.1), POST /capture-lead (UC_2.6.2), POST /execute-checkout at Step 6, and the Waitlist direct API calls to ActiveCampaign + Klaviyo (UC_2.1.3).

UC_2.1.2 — Geo-Based Compliance UI Variants (Flow A–J)

1. Overview

2. Trigger

required_flow (stored in global checkout state at Step 0) is read when Step 5 renders.

3. Routing Table

Sourced from checkout_ui_routing PostgreSQL table (Override Model: unmatched countries default to Flow A).

4. Standard Compliance Checkboxes (All Flows Except F)

Checkbox 1 — Commercial Acknowledgment:

"I acknowledge that I am purchasing a skills assessment software evaluation for commercial purposes to secure an independent contractor agreement with a US-domiciled C-Corporation, and I am not opening a retail financial, brokerage, or investment account."

Checkbox 2 — Age & Terms of Service:

"By clicking 'Complete Purchase', I confirm that I am at least 18 years of age and agree to the Terms of Service for the Data Processing and Performance Evaluation Service (Associate Track)."

Both: mandatory, default unchecked, displayed at Step 5 only.

Checkbox 2 — "Terms of Service" Click Behavior: The words "Terms of Service" inside the Checkbox 2 label are a clickable hyperlink. Clicking it opens a popup/modal (does not navigate away from Step 5, does not close/reset the checkout flow) displaying the Terms of Service content. Content is identical to the public /terms page (Ref: UC_29) — same legal text, same numbered sections, same "Last Updated" timestamp. This supersedes the prior distinct-document framing in UC_29 BR-29-03/A-10 (see changelog note there). Closing the popup (via close button or overlay click) returns the user to Step 5 with checkbox state and all other form data unchanged.

5. Flow B — Pass-Rate Disclosure (UK & Australia)

Static text block at Step 5, above standard checkboxes. Same text for UK and Australia.

• If is_launch_phase == TRUE:

  "This is a newly launched proprietary trading evaluation program. Historical pass-rate and success data is currently unavailable."

• If is_launch_phase == FALSE:

  "Historically, only [historical_pass_rate]% of participants successfully pass the evaluation to become authorized traders."

6. Flow C — EU/EEA Additional Checkbox

Checkbox 3 — EU 14-Day Withdrawal Waiver:

"I expressly consent to the immediate commencement of the digital evaluation service and waive my 14-day right of withdrawal under EU consumer protection law."

Default: unchecked. Mandatory. Positioned between standard checkboxes and the Next button.

7. Flow D — Quebec Localization

Entire checkout UI (Steps 1–7) renders in French. All labels, placeholders, button text, and ad copy within the checkout are localized to French.

8. Flow E — UAE Disclaimer

Static text block at Step 5, above standard checkboxes:

"Stack Trading is a U.S.-domiciled entity and is not licensed, registered, or regulated by the Dubai Financial Services Authority (DFSA) or the Abu Dhabi Global Market (ADGM)."

9. Hypothetical Performance Disclaimer (All Flows)

Mandatory legally-required static text block at Step 5 for all flows:

"HYPOTHETICAL OR SIMULATED PERFORMANCE RESULTS HAVE CERTAIN LIMITATIONS. UNLIKE AN ACTUAL PERFORMANCE RECORD, SIMULATED RESULTS DO NOT REPRESENT ACTUAL TRADING. ALSO, SINCE THE TRADES HAVE NOT ACTUALLY BEEN EXECUTED, THE RESULTS MAY HAVE UNDER-OR-OVER COMPENSATED FOR THE IMPACT, IF ANY, OF CERTAIN MARKET FACTORS, SUCH AS LACK OF LIQUIDITY. SIMULATED TRADING PROGRAMS IN GENERAL ARE ALSO SUBJECT TO THE FACT THAT THEY ARE DESIGNED WITH THE BENEFIT OF HINDSIGHT. NO REPRESENTATION IS BEING MADE THAT ANY ACCOUNT WILL OR IS LIKELY TO ACHIEVE PROFITS OR LOSSES SIMILAR TO THOSE SHOWN."

Static, always visible, non-collapsible. No user interaction.

7. Business Rules

BR_2.1.2.1: Flow-to-UI Mapping is Frontend-Hardcoded

The mapping of required_flow → specific UI content at Step 5 is hardcoded in the frontend. FE reads required_flow from global checkout state and renders the corresponding variant via a fixed enum switch. Changing what a flow displays requires a frontend code change. See §3 Routing Table for the full mapping.

BR_2.1.2.2: Country-to-Flow Assignment is Dynamic (DB-Driven)

Which country maps to which flow is managed via the checkout_ui_routing PostgreSQL table — configurable by Ops without a code deploy. Adding a new country rule only requires inserting a row into this table; it does not require a FE change.

UC_2.1.3 — Gate 1: Waitlist

1. Overview

References/Wireframe/Stage 1/Checkout Flow - Waitlist.png Waitlist — empty state References/Wireframe/Stage 1/Join waitlist (choosing asset).png Waitlist — dropdown open References/Wireframe/Stage 1/Join waitlist (Processing).png Waitlist — submitting References/Wireframe/Stage 1/Join waitlist (succeed).png Waitlist — success state References/Wireframe/Stage 1/Join waitlist - Invalid email.png Waitlist — validation error References/Wireframe/Stage 1/Checkout Flow - Fail due to error.png Waitlist — CRM API submit failed

2. Trigger

Global_Var_Allow_New_Signups == FALSE detected in the GET /system/status response.

3. Pre-conditions

• User is on the checkout page.
• GET /system/status returns Global_Var_Allow_New_Signups == FALSE.

4. Post-conditions

• Frontend makes direct API calls to BOTH Klaviyo and ActiveCampaign, sending the captured email and UTM parameters (read from localStorage at submit time, per CR-12 / BR_2.1.1.4) to each — no Zapier orchestration for either call.
• Page content replaced by success state. Ref: OV-04.
• Scope boundary: System responsibility ends at firing both direct API calls. Klaviyo automatically triggers the Waitlist_Welcome drip (Ref: KLA-22) — out of system; the marketing team manages that sequence's content/cadence. ActiveCampaign creates the CRM record and attaches identity to behavioral tracking — it does not send automated emails.

5. Basic Flow

1. GET /system/status returns Global_Var_Allow_New_Signups == FALSE.
2. Frontend redirects (client-side navigation, same tab) to the dedicated Waitlist page. The standard Marketing Header and Footer render on this page.
3. User selects primary market (Futures or Forex).
4. User enters email.
5. User clicks [Join Waitlist].
6. Button switches to "Processing..." (disabled). Frontend reads current UTM values from localStorage (per CR-12) and makes direct API calls to BOTH Klaviyo and ActiveCampaign, sending lead data (primary market + email) and those UTM parameters to each.
7. On success → page content replaced by success state. Ref: OV-04.
8. User clicks [Return to Homepage] → navigated to homepage.

6. Exceptional Flow

• [If CRM API fails on submit]

  • Ref: BN-02. [Join Waitlist] button remains available for retry.
  • Form data is NOT cleared.

7. Business Rules

BR_2.1.3.1: Global Scope

Global_Var_Allow_New_Signups == FALSE is a global toggle — redirects ALL countries to the Waitlist page simultaneously.

BR_2.1.3.2: No Interrupt Logic

If Global_Var_Allow_New_Signups changes to FALSE while a user is mid-checkout (started when Global_Var_Allow_New_Signups == TRUE), the user completes the ENTIRE checkout flow without interruption. Frontend does NOT re-check after initial page load.

BR_2.1.3.3: CRM-Side Deduplication (No Information Leakage)

No custom backend check or database query is built to verify waitlist status. ActiveCampaign and Klaviyo handle identity resolution and deduplication natively. If the submitted email already exists, the CRM silently deduplicates or updates the record — the frontend still transitions to the success UI state (Ref: OV-04) regardless, to prevent information leakage (i.e., never reveal whether an email is already registered). This applies identically to both the ActiveCampaign and Klaviyo direct API calls — both receive the same email + UTM payload.

8. Screen Description

Page Content Header: (rendered below the standard Marketing Header — Ref: UC_1.1.1)

Form Fields:

UC_2.1.4 — Gate 2: Geoblock

1. Overview

References/Wireframe/Stage 1/Flow F Gate 2 - Geoblock (Absolute).png Gate 2 — Geoblock full-page block

2. Trigger

GET /system/status returns HTTP 403 — geo_blocked == true because CF-IPCountry/CF-Region matches a row in Compliance_geo_restrictions.

3. Business Rules

BR_2.1.4.1: Hard Stop — Full Page Replacement

HTTP 403 = absolute hard stop. The geoblock state replaces the ENTIRE checkout UI — no header, nav, footer, step indicators, or appeal link. Only the block message is shown (message content includes a support contact email per FP-02).

4. Screen Description

Full-page 403 block — checkout UI fully replaced. Screen content defined at Ref: FP-02.

UC_2.1.5 — Pricing Engine

1. Overview

2. Business Rules

BR_2.1.5.1: Founder Cohort Detection

Frontend reads is_founder_cohort from the /system/status response:

• TRUE → display prices from the Founder Price column (Table J) for each tier.
• FALSE → display prices from the Challenge Price column (Table J) for each tier.

Prices are not hardcoded in the frontend — always read from the pricing_tiers object in the /system/status response. Actual values are managed centrally in Zapier Table J.

BR_2.1.5.2: Race Condition — Stale Pricing

Triggered at Step 6 (Pay click) when the server-side price/tax re-check (Ref: UC_2.8.1 §5 step 6.1.a) detects either of the following:

• Founder cohort sold out: Founder cohort slot filled up between page load and Pay click, reverting to Standard pricing.
• Tax rate changed: Tax rate changed server-side between POST /calculate-cart (Step 5) and POST /execute-checkout (Step 6), causing the total to differ.

In either case, the backend returns PRICE_CHANGED — no charge is created, no promo reservation occurs. Frontend dismisses Ref: OV-05 and surfaces Ref: OV-08.

[Refresh now] behavior: Clicking [Refresh now] on OV-08 closes the overlay and refreshes the Order Summary with the updated price/tax. No full page reload. The user may then click [Pay] again with the updated total.

BR_2.1.5.3: Price Data Source

Founder Prices and Standard Challenge Prices for all 3 tiers are stored in Zapier Table J. Backend reads the appropriate column and packs the values into the pricing_tiers object in the /system/status response at Step 3e. Frontend renders the 3 pricing cards at Step 2 from this object — no additional API call required.

(Source: Zapier Integration V7.pdf §3.7)

Note: Data above reflects current Ops configuration snapshot (source: Zapier Table J). All pricing values may be changed by Ops at any time without a code deploy.

Step 1: Asset Class Selection

UC_2.2 — Asset Class Selection

1. Overview

References/Wireframe/Stage 1/Checkout Flow - Step 1.png Asset Class Selection

2. Trigger

User passes Gate 1 and Gate 2 at Step 0.

3. Pre-conditions

• Global_Var_Allow_New_Signups == TRUE
• geo_blocked == FALSE
• /system/status response stored in global checkout state.

4. Post-conditions

• asset_class stored in session state.
• User proceeds to Step 2.

5. Basic Flow

1. Step 1 renders with 2 large selection cards: Futures and Forex.
2. User clicks one card.
3. Selection stored in session state.
4. User clicks [Next] to proceed.

6. Business Rules

BR_2.2.1: Fixed Options

2 asset class options (Futures, Forex) are fixed in the frontend — not driven by API. Both always displayed.

BR_2.2.2: Session Persistence

Asset class selection is stored in session state for the duration of the checkout flow. Persistence and reload/recovery behavior across a full page refresh is governed centrally by BR_2.1.1.3 (Step 0) — a refresh does NOT return the user to Step 1 as long as local storage cart state is present; see that rule for the exact per-step matrix.

BR_2.2.3: Asset Class Change — Progress Bar & Step Count Impact

Progress bar step count is dynamic — total number of steps differs by asset class:

• Futures: 7 steps — Step 1 → 2 → 3 → 4 (Market Data) → 5 → 6 → 7
• Forex: 6 steps — Step 1 → 2 → 3 → 5 → 6 → 7 (Step 4 omitted from flow)

This applies on initial selection at Step 1 and when navigating back to Step 1 to change selection. Progress bar re-renders to reflect the new total step count immediately on selection.

If user navigates back to Step 1 and changes asset class selection:

• Futures → Forex: Step 3 (Platform) selection is reset. Step 4 (Market Data) is removed from the flow; progress bar updates to show 6 steps total.
• Forex → Futures: Step 3 (Platform) selection is reset. Step 4 (Market Data) is added back to the flow; progress bar updates to show 7 steps total.

Step 5 (PII & Compliance) data is NOT reset on asset class change. Data is only fully cleared on full page refresh — see BR_2.2.2.

7. Screen Description

Step 2: Capital Allocation Selection

UC_2.3 — Capital Allocation Selection

1. Overview

References/Wireframe/Stage 1/Step 2 future standard price.png Capital Allocation — Futures, Standard price References/Wireframe/Stage 1/Step 2 future founder price.png Capital Allocation — Futures, Founder price References/Wireframe/Stage 1/Step 2 forex standard price.png Capital Allocation — Forex, Standard price References/Wireframe/Stage 1/Step 2 forex founder price.png Capital Allocation — Forex, Founder price References/Wireframe/Stage 1/Step 2 tooltip.png Capital Allocation — Live Stop Loss tooltip

2. Trigger

User clicks [Next] at Step 1 with an asset class selected.

3. Pre-conditions

• asset_class in session state.
• /system/status pricing data in global checkout state.

4. Post-conditions

• product_id (EVAL_L1, EVAL_L2, or EVAL_L5) stored in session state.
• User proceeds to Step 3.

5. Evaluation Package Data

Values above are a current snapshot — Tables A, B, C, and J are Ops-editable without a code deploy; frontend/backend must fetch live from /system/status, not hardcode.

Daily Loss Limit (Daily_Loss_Ratio × max_drawdown) is a backend/ops metric — it is not displayed in the Step 2 checkout UI. Daily_Loss_Ratio is read from Table C at runtime.

6. Business Rules

BR_2.3.1: Pricing Mode — Standard vs Founder

Frontend reads is_founder_cohort from /system/status.

• TRUE → Founder mode: each card renders the original Standard Price with strikethrough (~~$7,000~~) followed by the Founder Price at full size ($5,599). The "one-time" label is NOT shown.
• FALSE → Standard mode: each card renders only the Standard Price followed by the "one-time" label (e.g., $7,000 one-time). No strikethrough.

BR_2.3.2: Card Selection

Clicking a card body to select that tier. Only one card can be selected at a time; selecting a new card deselects the previous one. The card's selected state is reflected visually on the card.

The [Next] button at the bottom of the page is a separate navigation control — it is disabled until a card is selected (see §7 Screen Description).

7. Screen Description

Step 3: Platform Selection

UC_2.4 — Platform Selection

1. Overview

References/Wireframe/Stage 1/Checkout Flow - Step 3 (Future).png Platform Selection — Futures References/Wireframe/Stage 1/Checkout Flow - Step 3 (Forex).png Platform Selection — Forex References/Wireframe/Stage 1/Checkout Flow - Step 3 - No platforms available.png Platform Selection — No platforms available

2. Trigger

User clicks [Next] at Step 2 with a package selected.

3. Pre-conditions

• asset_class in session state.

4. Post-conditions

• platform stored in session state.
• User proceeds to Step 4 (Futures) or Step 5 (Forex — Step 4 skipped).

5. Platform Registry (Zapier Table I)

Platform availability is controlled by the Is_Active flag in Zapier Table I. Ops can enable or disable any platform at any time without a code deploy.

Note: Data above reflects current Ops configuration snapshot (source: Zapier Table I). Is_Active and Risk_Group_Template may be changed by Ops at any time without a code deploy — frontend must fetch this table dynamically (via GET /public/platform-options), not hardcode it. TradeSea replaces NinjaTrader 8, same asset class and gateway — source table snapshot still lists NinjaTrader 8, superseded by CR.

6. Basic Flow

1. Step 3 renders.
2. Frontend calls GET /public/platform-options?asset_class=[asset_class].
3. Platform options render as logo-driven selection tiles.
4. User clicks a tile → stored in session state.
5. User clicks [Next].

7. Exceptional Flow

• [If GET /public/platform-options returns empty array]

  • Ref: OV-01.

• [If GET /public/platform-options returns HTTP 500 or network timeout]

  • Full-page error: FP-03.

8. Business Rules

BR_2.4.1: Dynamic List — No Hardcoding

Platform options fetched from GET /public/platform-options?asset_class=[asset_class].

Response structure returns only an array of Platform_Name strings (e.g. { "platforms": ["TradeSea", "Quantower"] }) — no logo/icon field exists in the response schema.

Platform logos are static frontend assets; the frontend is responsible for mapping each returned Platform_Name string to its corresponding local logo asset (no backend-provided icon URL).

BR_2.4.2: Pre-selection with 1 Result

1 platform returned → auto pre-select (highlighted). User must still click [Next] — no auto-advance.

BR_2.4.3: Navigation — Back from Later Steps

Changing platform by navigating back from Step 5 → Market Data (Step 4) is NOT reset (independent). Step 5 data is NOT reset.

9. Screen Description

Step 4: Market Data Selection

UC_2.5 — Market Data Selection (Futures Only)

1. Overview

References/Wireframe/Stage 1/Checkout Flow - Step 4.png Market Data Selection (Futures only)

2. Trigger

User clicks [Next] at Step 3 AND asset_class == 'FUTURES'.

3. Pre-conditions

• asset_class == 'FUTURES'
• GET /public/market-data-products returns a non-empty array.

4. Post-conditions

• addon_ids[] array stored in session state.
• User proceeds to Step 5.

5. Basic Flow

1. Step 4 renders.
2. Frontend calls GET /public/market-data-products. Backend fetches the product list and per-feed prices from Zapier Table C (Global Variables) — prices are never hardcoded in backend code (see BR_2.5.5).
3. Renders selection grid of toggle switches.
4. CME: pre-checked and locked (cannot be toggled OFF).
5. User toggles optional feeds (NYMEX, CBOT, COMEX) as desired.
6. All selected feeds display: "Cost: $0.00 (Covered by Stack Trading)".
7. User clicks [Next].

6. Exceptional Flow

• [If GET /public/market-data-products returns 0 products]
  • Full-page error: FP-03. Treated as system error.

7. Business Rules

BR_2.5.1: CME Locked ON

CME is pre-checked and locked (locked ON) by default — cannot be unchecked by the user.

BR_2.5.2: Optional Feed Defaults

NYMEX, CBOT, COMEX default to unchecked (OFF). User actively toggles to ON.

BR_2.5.3: Cost Display

All selected options display "Cost: $0.00 (Covered by Stack Trading)". Downstream billing (Level 1–2 pay; Level 3+ reimbursed) is handled by Zapier Flow 22 (Monthly Data Fee Billing) — not surfaced here. (Source: Zapier Integration V7.pdf, Flow 22)

BR_2.5.4: Navigation — Back from Later Steps

If the user proceeds past Step 4 and later navigates back to Step 4 (e.g. Back button, or editing a prior step), the previously selected addon_ids[] toggle states are preserved and re-rendered as-is (CME still locked ON; any optional feeds the user had toggled ON remain ON). Selections are not reset to default.

BR_2.5.5: Product & Price Source — Table C (No Hardcoding)

GET /public/market-data-products MUST read the product list (id, name) and per-feed price (e.g. NYMEX_Bundle) from Zapier Table C (Global Variables) at request time. Backend code must not hardcode product IDs or prices — Table C is the single source of truth so Ops can change pricing without a deploy. This rule also applies to the authenticated dashboard variant GET /market-data-products (see Market Data Management, Dashboard Settings), which reads from the same Table C but additionally filters out feeds the user already owns. (Source: RFQ_ Stack Trading Prop Tech V7.pdf §3.2, Market Data Products / Public Market Data API — "Do not hardcode prices"; client confirmation 2026-07-31.)

8. Screen Description

Step 5: PII Capture, Compliance & Cart Abandonment

UC_2.6.1 — PII Capture & Compliance

1. Overview

References/Wireframe/Stage 1/Step 5 Flow A.png PII & Compliance — Flow A (Standard — US & most regions) References/Wireframe/Stage 1/Step 5 Flow B_ Data available.png PII & Compliance — Flow B (UK/AU, pass rate data available) References/Wireframe/Stage 1/Step 5 Flow B_ Launch state (Data unavailable).png PII & Compliance — Flow B (UK/AU, launch state) References/Wireframe/Stage 1/Step 5 Flow C Data available.png PII & Compliance — Flow C (EU/EEA, data available) References/Wireframe/Stage 1/Step 5 Flow C Launch state (Data unavailable).png PII & Compliance — Flow C (EU/EEA, launch state) References/Wireframe/Stage 1/Step 5 Flow D.png PII & Compliance — Flow D (Canada) References/Wireframe/Stage 1/Step 5 Flow E.png PII & Compliance — Flow E (UAE) References/Wireframe/Stage 1/Step 5 Flow G.png PII & Compliance — Flow G (India)

2. Trigger

User clicks [Next] at Step 4 (Futures) or Step 3 (Forex).

3. Pre-conditions

• Session state: asset_class, product_id, platform, addon_ids[].
  • For the Forex path (Step 4 skipped): addon_ids must be present as an empty array [].
• required_flow available in global checkout state.

4. Post-conditions

• All PII data validated.
• POST /calculate-cart returned HTTP 200 (Sanctions Gate passed).
• All required compliance checkboxes checked.
• User can click [Next] to proceed to Step 6.

5. Basic Flow

1. Step 5 renders with all PII input fields. Flow-dependent compliance UI renders simultaneously per UC_2.1.2 (required_flow).

2. Current UTM values are read from localStorage (per CR-12 / BR_2.1.1.4) — not re-parsed from the URL here.

3. User fills all fields. On Email field onBlur → triggers UC_2.6.2 Phase 1 (Capture Lead), independent of the flow below.

4. User selects Country. State/Province/Region and ZIP / Postal Code fields are all visible on initial Step 5 load. On Country selection, frontend re-evaluates both fields: if the selected country has no subdivisions → hide State/Region; if zip_requirements[billing_country] = false → hide ZIP. Otherwise the field stays visible.

5. Sanctions pre-check (Ref: BR_2.6.1.1): on Country selection and on State/Region selection, the system immediately checks whether the selected value is a blocked jurisdiction.

   • Blocked → the warning defined in IN-01 displays immediately, and Region/ZIP fields are disabled per BR_2.6.1.9.
   • Not blocked → no warning; user continues filling the form.

6. User checks all required compliance checkboxes and fills the remaining fields.

7. User clicks [Next]. Frontend calls POST /calculate-cart (Ref: BR_2.6.1.1):

   • Input: product_id, addon_ids, billing_country, billing_region, user_ip, user_id, promo_code (NULL at Step 5), zip_code (included only when zip_requirements[billing_country] = true; omitted otherwise).

   While this call is in flight, frontend displays the text "Calculating regional taxes..." directly below the State/Region dropdown, and [Next] is disabled (Ref: BR_2.6.1.2).

   Backend processes, in order (5 steps):

   Step	Name	Logic
   1	Sanctions Gate	Full request payload:product_id, addon_ids, billing_country, billing_region, zip_code (included only when zip_requirements[billing_country] = true; omitted otherwise), user_ip, user_id, promo_code (NULL at Step 5).- Validate billing_country + billing_region against Compliance_geo_restrictions (same table/query logic as UC_2.1.1 §5 Step 3a).- If a match is found where country = billing_country AND (region = 'All' OR region = billing_region) → return HTTP 403 immediately. See IN-01 for the exact user-facing message.- Steps 2–5 are skipped when this returns HTTP 403.
   2	Pricing Engine	- Ifproduct_id is EVAL_L1/EVAL_L2/EVAL_L5: query Table J (Evaluation and Reset Pricing) for the base price.- If Global_Var_Founder_Cohort_Open == TRUE (Table C), the backend queries the Founder Price column in Table J instead of the Standard Price column — this sets a lower base_price directly (not a discount on top of Standard Price). See UC_2.1.5.- Returning user detection [CHR-38]: if the entered email matches an existing Users record with status IN ('Failed', 'Terminated'), the engine must additionally branch on days_since_failure vs. Discount_Code_Duration_Days (Table C) and is_founder/is_professional to select locked_reset_price / locked_rebuy_price / Retry_Discount-adjusted price instead of full Challenge Price — kept in sync with the Dashboard Failure Modal and Klaviyo email pricing. Not yet fully elaborated in this UC — full branch logic documented in References/CR/2026-08-02_CR38_returning-user-checkout-pricing/CR_summary.md (Ref: [CHR-38]) and in the Failure/Recovery research docs; needs a dedicated BR write-up here before dev handoff.- Otherwise, fetch prices for product_id + addon_ids.- promo_code = NULL at Step 5 → discount_amount = 0.- During the evaluation phase, all addon_ids are $0 ("Covered by Stack Trading").- Math: Final_Amount = (base + addons) - discount_amount
   3	Location Check	- Ifbilling_country is missing, query the Users table via user_id to retrieve it.- Not applicable at Step 5 — billing_country is always supplied by the user's own form input here.- This step only triggers for the authenticated Dashboard reuse of this endpoint (see BR_2.6.1.1).
   4	Tax Engine	- Ping the third-partyQuaderno API with user_ip, billing_country, billing_region, zip_code (included only when zip_requirements[billing_country] = true; omitted otherwise), and the running amount computed in Step 2 (base_price − discount_amount).- Quaderno checks whether the buyer's jurisdiction has crossed a tax threshold (e.g. EU VAT, APAC GST) or qualifies for a domestic exemption. If not, tax_amount = 0; otherwise Quaderno returns the applicable tax_amount.
   5	Return	- Return{ base_price, discount_amount, tax_amount, total_price } to the frontend, where total_price = base_price − discount_amount + tax_amount.- At Step 5 this is saved silently to session state (see BR_2.6.1.5) — nothing is rendered.- At Step 6 the same shape populates the Order Summary.

8. If POST /calculate-cart returns HTTP 200: the "Calculating regional taxes..." text disappears. Triggers UC_2.6.2 Phase 2 (full PII UPSERT), then navigates to Step 6. No price/tax is shown at this step (see BR_2.6.1.5).

6. Exceptional Flow

• [Selected Country or State/Region is a blocked jurisdiction]

  • The warning defined in IN-01 displays immediately on selection.
  • Placement rules (mutually exclusive):
    • region = 'All' matched (entire country blocked) → warning displays under the Country field; State/Region and ZIP fields are disabled (Ref: BR_2.6.1.9).
    • region = [specific region] matched → warning displays under the State / Province / Region field; ZIP field is disabled (Ref: BR_2.6.1.9).
  • [Next] remains disabled.
  • Warning auto-clears, and disabled fields re-enable, the next time a valid (non-restricted) Country/State combination is selected.

• [If POST /calculate-cart returns HTTP 5xx]

  • Full-page error: FP-03. Full-page error screen replaces checkout UI.

7. Business Rules

BR_2.6.1.1: Sanctions Pre-Check & Tax Calculation Timing [CHR-47]

Two independent mechanisms — replaces the prior debounced-per-field-settle design entirely:

1. Sanctions pre-check (immediate): on every Country selection AND every State/Region selection, the system immediately checks whether the selected value is a blocked jurisdiction (same restricted-jurisdiction data as the Sanctions Gate below).
   • Blocked → the IN-01 warning displays immediately. State/Region and/or ZIP fields are disabled per placement rules — Ref: BR_2.6.1.9.
   • Not blocked → no warning; fields stay enabled.
   • Does not apply to Email or Confirm Email.
2. Tax calculation call on [Next] click: POST /calculate-cart fires only when the user clicks [Next] (Ref: §5 Basic Flow step 7) — not on any field's onChange/onBlur. Email and Confirm Email field changes never trigger this call (Ref: BR_2.6.1.7, unchanged). While the call is in flight, "Calculating regional taxes..." displays and [Next] is disabled (Ref: BR_2.6.1.2). The Sanctions Gate inside this call (Ref: §5 Basic Flow step 7 table, Step 1) remains the authoritative server-side check.

BR_2.6.1.2: Next Button Gate

[Next] is disabled until ALL conditions are simultaneously met:

1. All required fields have valid data.
2. No unresolved Sanctions pre-check match is active (Ref: BR_2.6.1.1 mechanism 1) — the currently selected Country/State combination is not a blocked jurisdiction.
3. All required compliance checkboxes are checked.
4. Confirm Email is filled and matches the Email field (Ref: BR_2.6.1.7).

On click, if conditions 1–4 above are met, [Next] triggers POST /calculate-cart (Ref: BR_2.6.1.1 mechanism 2) and stays disabled while that call is in flight ("Calculating regional taxes..." showing). Only on HTTP 200 does navigation to Step 6 actually proceed (Ref: §5 Basic Flow step 8).

BR_2.6.1.3: Everflow Cookie Capture

Everflow first-party cookie & S2S Attribution Fallback:

On Step 5 page initialization, the frontend runs the following two paths in parallel — both are mandatory and always execute on every page load, regardless of SDK status:

• Path 1 — Everflow SDK: Frontend initializes the Everflow JavaScript SDK (installed via NPM). Using the SDK helper methods, frontend captures the Affiliate ID and Offer ID from the URL parameters, executes the click client-side, and stores the generated transaction_id as a first-party cookie. At Step 6, everflow_id is read from this cookie via getTransactionId() and appended as a hidden payload parameter to POST /execute-checkout.
• Path 2 — Direct affiliate cookie: Frontend parses the raw affiliate URL parameters (affid, oid, ef_tok) directly from the browser URL and writes them into a first-party cookie named st_affiliate_data. This write does not route through the Everflow SDK and is therefore not blocked by ad blockers.

Everflow SDK failure behavior — S2S Fallback:

If the Everflow SDK fails to load (e.g. blocked by an ad blocker or network error), the failure is silent — Step 5 rendering is NOT blocked. The following S2S fallback sequence applies:

1. Frontend appends everflow_sdk_blocked: true (boolean flag) to the hidden payload sent to POST /execute-checkout.
2. Frontend passes the st_affiliate_data cookie content to POST /execute-checkout alongside the other payload parameters.
3. Backend — On-the-fly Transaction Generation: If the Node.js middleware receives everflow_id = null but st_affiliate_data is present, it invokes Everflow's Server-to-Server (S2S) Click API directly from the server to generate a transaction_id before processing the conversion postback.

BR_2.6.1.4: Data Persistence on Back Navigation

Step 5 data is preserved across back navigation (same general rule as BR_2.2.3). Reload/refresh behavior at Step 5 is governed centrally by BR_2.1.1.3 (Step 0) — data is kept, not cleared, as long as local storage cart state is present.

BR_2.6.1.5: No Price Display at Step 5

Step 5 does not render base_price, tax_amount, total_price, or any other line item from the POST /calculate-cart response. The response is held in session state only; the Order Summary is first rendered at Step 6.

BR_2.6.1.6: ZIP / Postal Code Dynamic Validation

The ZIP / Postal Code field is visible by default on Step 5 load. Its required/optional state and visibility after Country selection are driven entirely by zip_requirements, read from the global checkout state populated by UC_2.1.1 GET /system/status.

On Country onChange: requires_zip = true → field stays visible and is required; requires_zip = false → field is hidden from the UI.

Only a Country change re-evaluates this rule — a State/Region change does not. billing_address and zip_code are both stored in session state and forwarded to the payment gateway at POST /execute-checkout for AVS (Address Verification System) check; there is no secondary billing address support — only the address collected at Step 5 is used for payment verification.

BR_2.6.1.7: Confirm Email — Frontend-Only Match Validation [CHR-18]

The Confirm Email field has no database column and is never included in any API payload (POST /capture-lead, POST /execute-checkout, or any other endpoint).

Sequencing:

1. Email field onBlur → runs format validation, then Company Email Domain Block (Ref: BR_2.6.1.10) — a blocked domain halts here (Ref: IN-11). Phase 0 (Blacklist Check + Duplicate Account Check, Ref: UC_2.6.2 §5 Phase 0 — Blacklist Check & Duplicate Account Check) only runs if this gate is passed. Inline error displays immediately if any gate fails.
2. Confirm Email field onBlur → validates format, checks Company Email Domain Block (Ref: BR_2.6.1.10), then compares against Email:
   • 2.1. Match: No error. If Phase 0 has already passed for the current Email value, Phase 1 (POST /capture-lead) fires.
   • 2.2. Invalid format: Ref: IN-07. Phase 1 does not fire.
   • 2.3. Blocked domain: Ref: IN-11. Phase 1 does not fire. Checked independently of the Email field's own result — Ref: BR_2.6.1.10.
   • 2.4. Valid format, not blocked, but mismatch: Ref: IN-05. Phase 1 does not fire.
3. POST /capture-lead fires only when Phase 0 has passed AND Confirm Email matches (step 2.1).

Editing Email after Confirm Email already matched it:

Confirm Email must be re-validated against the new Email value:

• If it no longer matches → Ref: IN-05 renders under Confirm Email: "Emails do not match" (same as step 2.3).
• If it still matches → since the Email value changed, Email must go through Phase 0 again (Ref: UC_2.6.2 §5 Phase 0 — Blacklist Check & Duplicate Account Check):
  • New Email matches an existing DB record → follow the Duplicate Account Check matrix (Ref: UC_2.6.2 §5, Duplicate Record table) — e.g. UPSERT onto the existing Guest record where applicable, or block per the matrix.
  • New Email has no existing record → proceed with the normal Phase 0 → Phase 1 flow (new Guest record).

Re-matching Confirm Email against an Email value that has NOT changed does not re-fire POST /capture-lead — Phase 1 only fires again when the Email value itself has actually changed.

BR_2.6.1.8: Invalid Field Data Display on Reload / Navigation

Applies to the 4 free-text fields at Step 5 with a format or length rule: Full Name, Email, Billing Address, ZIP / Postal Code.

At the moment checkout state is re-rendered — full page refresh (F5, per BR_2.1.1.3 Table 1), backward navigation ([Back]), or forward navigation ([Next]) — if a field holds previously-entered data that fails its format/length rule, the invalid data is displayed with an inline error message and red border.

Explicit exclusion — NULL/empty fields: if a field is NULL or empty (never filled, or cleared by the user before leaving the step), this rule does not apply and no error is shown automatically on reload/navigation.

BR_2.6.1.9: Field Disable on Sanctions Pre-Check Match

When the Sanctions pre-check (Ref: BR_2.6.1.1 mechanism 1) matches the selected Country or State/Region against a blocked jurisdiction:

• Country match (region = 'All'): State/Province/Region field (if visible) AND ZIP / Postal Code field (if visible) both become disabled.
• State/Region match (region = [specific region]): ZIP / Postal Code field (if visible) becomes disabled. State/Region itself stays enabled (user may pick a different region).

Fields re-enable automatically the moment the user changes the Country (or Region, for the region-match case) to a value that is not a blocked jurisdiction. Disabling does not clear any value the user had already entered into ZIP / Region — it is restored (still visible, greyed out) if the user re-selects the same blocked value again.

BR_2.6.1.10: Company Email Domain Block (Email & Confirm Email)

Domain check: value's domain is @stacktrading.com → Block.

Email field onBlur — check order:

1. Format validation (Ref: CR-09 §9.1) — fails here, halts.
2. Company Email Domain Block: If domain is @stacktrading.com → HALT. Phase 0 (Blacklist Check / Duplicate Account Check, Ref: UC_2.6.2 §5) only runs if this gate is passed.

Confirm Email field onBlur — check order (extends BR_2.6.1.7):

1. Format validation (IN-07 on failure).
2. Company Email Domain Block: If domain is @stacktrading.com → HALT (IN-11). Match comparison against Email only runs if this gate is passed. Checked independently of the Email field's own result — covers the case where a user populates Confirm Email (paste/autofill) before the Email field has ever been blurred.

On block (either field): Inline error IN-11 renders beneath the field that triggered it. [Next] stays disabled — hard stop, same pattern as IN-02/IN-03, Ref: BR_2.6.1.2 condition 1. No Guest row is written for a blocked Email value.

8. Screen Description

UC_2.6.2 — Lead Capture & Cart Abandonment (Three-Phase)

1. Overview

2. Trigger

• Phase 0: Email field onBlur at Step 5 — runs Blacklist Check and Duplicate Account Check. If either gate blocks → flow stops (see Phase 0 in §5 Basic Flow).
• Phase 1: Both Phase 0 gates pass, AND Confirm Email is filled, valid, and matches Email (Ref: BR_2.6.1.7) → POST /capture-lead fires async (background, no UI change).
• Phase 2: User clicks [Next] at Step 5 with all BR_2.6.1.2 conditions satisfied.

3. Pre-conditions

• Phase 0: Email field contains a value in valid email format.
• Phase 1: Both Phase 0 gates (Blacklist Check and Duplicate Account Check) have passed, AND Confirm Email is filled, valid, and matches Email.
• Phase 2: All BR_2.6.1.2 (Next Button Gate) conditions are met.

4. Post-conditions

• Phase 0 — blocked (Company Email Domain Block, Blacklist, or Duplicate Account Check): No Users row is written. [Next] is disabled and an inline warning is shown beneath the Email field (or Confirm Email field, if the block is on that field's own domain check — Ref: BR_2.6.1.10) (see Phase 0 in §5 Basic Flow).
• Phase 1 — succeeded: A row in the Users table with status = 'Guest' exists for this email — newly created on the user's first-ever visit, or updated in place if a Guest row for this email already existed (e.g. re-entry, see BR_2.6.2.3). Cart_Abandonment webhook fired to Zapier automation bus.
• Phase 2: The same Guest row is updated with full PII and session data. user_id returned and stored in session state. User navigated to Step 6.

5. Basic Flow

Confirm Email Gate — Confirm Email onBlur:

3. Check Confirm Email: On Confirm Email field onBlur:
   • 3a. Invalid format: If the value is not a valid email format → display Ref: IN-07 ("Please enter a valid email address") and HALT.
   • 3b. Mismatch: If the value is a valid format but does not match the Email field → display Ref: IN-05 ("Emails do not match") and HALT. (see BR_2.6.1.7).

Phase 1 Trigger:

4. Capture Lead: Once Email has passed gates (1) and (2), AND Confirm Email has passed gate (3), silently call POST /capture-lead in the background (Phase 1). This fires from whichever field's onBlur completes the full condition set last.

Phase 0 — Blacklist Check & Duplicate Account Check:

Company Email Domain Block runs first, immediately after format validation passes on Email onBlur (Ref: BR_2.6.1.10). If the email's domain is @stacktrading.com → HALT immediately — no Users row is written, [Next] is disabled, inline warning IN-11 renders beneath the Email field. Blacklist Check and Duplicate Account Check do not run.

The two checks below run on Email onBlur only when the domain is not blocked, and act as the primary gate before any capture-lead call fires.

Blacklist Check runs next. Query the blacklist table (schema below) WHERE email = payload.email AND is_active = TRUE. A match HALTs the flow — no Users row is written, [Next] is disabled, and inline warning Ref: IN-02 renders beneath the Email field. [CHR-17]

blacklist Table Schema:

Duplicate Account Check runs only after the Blacklist Check clears, and evaluates the existing Users record (if any) for this email against the four branches below:

If no existing record matches at all, the check also allows the flow through (first-ever visit with this email).

Phase 1 — Capture Lead (Confirm Email onBlur, once all gates pass):

1. Once Phase 0 gates (1)–(2) and the Confirm Email Gate (3) have all passed → proceed to Phase 1 (Capture Lead).

2. Frontend calls POST /capture-lead (fires async, in the background — no spinner, no UI change while pending), with input: email (required), full_name (optional), utm_source (optional — read from localStorage per CR-12 / BR_2.1.1.4; not re-parsed from the URL here), abandoned_step (optional).

   • abandoned_step: Records the furthest step the user has ever reached for this row — monotonic, never regresses on re-entry. See BR_2.6.2.10. All possible values the backend can insert:

   Value	Trigger point
   "Step 5: PII & Details"	EmailonBlur at Step 5
   "Step 6: Payment"	User clicks[Next] from Step 5 → arrives at Step 6 (Checkout & Payment)
   "Step 7: Order Processing"	User clicks[Complete Purchase] on Step 6 → payment submitted
   "Step 7: Claim Account"	User reaches the Provisioning Gate (Claim Account — Phase 2 of Step 7)
   "Completed"	POST /claim-account returns session token successfully (Step 7 Phase 2 complete)

   [CHR-14] 'Completed' state — Klaviyo Kill Signal: When POST /claim-account returns HTTP 200, the backend sets abandoned_step = 'Completed' and fires a completion event to the Zapier automation bus to cancel the abandonment nurture sequence for this user. [CHR-14]

3. UPSERT (keyed by email) on the core Users table, runs server-side inside POST /capture-lead:

   • First-ever visit with this email → no existing row matches → backend INSERTs a new row with status = 'Guest', using the abandoned_step value passed up in the request.
   • Re-entry with an email already captured before (see BR_2.6.2.3) → an existing Guest row matches → backend UPDATEs that same row instead of creating a duplicate (abandoned_step follows the monotonic rule — see BR_2.6.2.10).
   • There is no separate "Capture Lead" table — this always writes to the same Users row (see BR_2.6.2.5).
   • "Pending Order" is only the conceptual label ActiveCampaign/Klaviyo uses to track this record; it is not a DB status value.
   • Backend fires outbound webhook event Cart_Abandonment → Zapier automation bus.

4. Zapier triggers a Klaviyo lifecycle email nurture campaign (see BR_2.6.2.7 for scope boundary).

5. Backend returns HTTP 200 OK. No visible UI change — no spinner, no banner. Public endpoint, no Auth required.

Phase 2 — Full PII UPSERT (Next click):

6. User clicks [Next] at Step 5 (all BR_2.6.1.2 conditions met).
7. System performs an UPSERT on the same Guest record keyed by email:
   • status = 'Guest'
   • All PII fields (name, email, billing address, zip_code, country, region, shirt size).
8. System returns user_id → stored in session state. (transaction_id does not exist yet at this point — it is only generated later, at Step 6 checkout/payment execution)
9. Frontend navigates user to Step 6.

5a. Exceptional Flow

• [Phase 1 — POST /capture-lead returns HTTP 5xx or times out]
  • Silent failure — no error UI shown (background lead-capture call, not a blocking step). Does not disable or delay [Next]; Phase 2 still runs its own UPSERT independently.
• [Phase 0 — Company Email Domain Block, Blacklist Check, or Duplicate Account Check blocks the user]
  • [Next] stays disabled until the user changes the blocked field (Email and/or Confirm Email) to a value that clears all checks.
• [User closes the browser or navigates away before clicking [Next], after Phase 0 & Phase 1 already ran]
  • See BR_2.6.2.6 / BR_2.1.1.3 — no login gate exists for this; the existing Guest record is simply updated (UPSERT) the next time the user re-enters an email on Step 5.

6. Business Rules

BR_2.6.2.1: Trigger — Three Sequential Phases

Phase 0 (Gates) is triggered by Email field onBlur. Phase 1 (Guest record creation/update + Cart_Abandonment webhook) requires BOTH Phase 0 to have passed AND Confirm Email to have been filled, validated, and matched against Email — it is not triggered by [Next]. See BR_2.6.1.7 for the full Confirm Email sequencing and the re-fire rule when Email is edited after a match.

Phase 2 ([Next] click) performs an additional UPSERT of full PII onto the same record and does not re-fire the Cart_Abandonment webhook.

Edge case — [Next] clicked without the Email or Confirm Email field ever losing focus (e.g. users fill in all other fields first, then click "Next" without blurring either field): Phase 0 and Phase 1 have not run, so no Guest row exists yet for this email. Frontend must run Phase 0 gates, the Confirm Email match check, and Phase 1 (§5) first — synchronously, before Phase 2's UPSERT — so the Cart_Abandonment webhook still fires and the row exists before Phase 2 updates it.

BR_2.6.2.2: Email onBlur — Debounce

Frontend starts a 500ms debounce timer on onBlur. If the user refocuses the email field within 500ms (e.g. to fix a typo) and blurs again, the pending call is cancelled and the timer resets. POST /capture-lead only fires after the email field has been blurred and remained unfocused for the full 500ms.

BR_2.6.2.3: Email onBlur — Change-Detection

POST /capture-lead only fires if the email that just passed the debounce timer is different from the last email successfully submitted. If the user blurs the same email again (e.g. accidentally refocuses and blurs without changing the value), no duplicate API call is made.

BR_2.6.2.4: Email Change — Old Guest Row Handling

When a user changes their email address and the new email passes both the debounce timer (BR_2.6.2.2) and the change-detection check (BR_2.6.2.3), a new Guest row is created for the new email. The old email’s Guest row is not deleted immediately — it is cleaned up by the existing 30-day cron job defined in BR_2.6.2.8.

BR_2.6.2.5: Guest Record Schema — No Separate Table

There is no dedicated “Capture Lead” table. The email is written directly to the core Users (PostgreSQL) table with status = 'Guest'. The full Users table schema (all columns) is documented at Step 7.

BR_2.6.2.6: Re-entry Handling — No Login Gate

There is no Auth0 account for a Guest record at any point before Step 7 is completed, so a “login” cannot occur for these users. Re-entry (whether via reload, back navigation, or a deep-link) is instead governed centrally by BR_2.1.1.3 (Step 0).

BR_2.6.2.7: Klaviyo Scope Boundary

Sotatek’s responsibility ends at firing the Cart_Abandonment webhook (Phase 1) to the Zapier automation bus. Klaviyo email campaign is orchestrated by Zapier — out of scope for Sotatek implementation.

BR_2.6.2.8: Guest Record Auto-Delete [CHR-19]

A background cron job runs periodically and hard-deletes records matching BOTH conditions:

• status = 'Guest'
• created_at < NOW() - INTERVAL '30 days'

Note: Deletion is based on created_at (original record creation date), not updated_at. A record that was created 30 days ago and still has not converted is deleted — regardless of any subsequent updates to it.

BR_2.6.2.10: abandoned_step — Monotonic Progression Guard

abandoned_step must always reflect the furthest step the user has ever reached for that row, never the current/latest one. On every write (Phase 1 UPSERT or any later re-entry UPDATE), the backend compares the incoming step against the stored value using a fixed ordinal rank and only overwrites if the incoming rank is strictly greater:

Effectively abandoned_step = GREATEST(rank(stored), rank(incoming)), resolved back to the value name. Example: user reaches Step 7: Order Processing then reloads and lands back on Step 5 → abandoned_step stays Step 7: Order Processing; it does not regress to Step 5: PII & Details.

Source: Client instruction (chat), 2026-07-30.

Changelog

| Date | Version | Updated Item | Before | After | Notes |

| 2026-09-03 | v20 | UC_2.3 §5 "Evaluation Target / Stop" row + §7 Screen Description Row 1 (Evaluation Requirements box, Row 2 text) | Labeled "14% Target / 7.5% Stop (Static)" with Source "Fixed (no Zapier table to config)" — both percentages hardcoded as static literals in the UI copy. | Corrected to (Dynamic) — both percentages are Ops-editable Zapier Table C fields: SIM_target_percent (default 14%) and SIM_stop_percent (default 7.5%). Source column updated to Table C (SIM_target_percent / SIM_stop_percent) [CHR-49]. 60 days remains a separate fixed literal (Today + 60 Days, no Table C field — Ref: Zapier Integration V7.pdf, Flow 3A Step "Store expiration_date"), called out explicitly so it isn't conflated with the two dynamic percentages. §7 Row 2 UI copy changed from a static string literal to a dynamically-rendered template. | User audit finding, 2026-09-03. Both SIM_stop_percent and SIM_target_percent confirmed under [CHR-49] — per official CHR mapping table docs/BA/Impact_matrix_CR/CHR_Tag_Impact_Matrix_20260821_v1.md L156: CR-20260820-001 \| CHR-49 \| SIM stop/target percent. CR_summary.md's own "Nội dung thay đổi cụ thể" section only details the stop-percent formula rewrite (scoped to UC_4.10.1/UC_4.10.2, which have no Profit Target) and its Open Questions line notes SIM_target_percent wasn't raised as a formula change for UC_4.8.1/UC_4.10.4 specifically — that is a scope note for those UCs, not a statement that SIM_target_percent sits outside CHR-49. The raw CR-index CSV row (line 427-437, client Adrian, Slack thread 2026-08-14) requests both fields as one combined Table C addition, and UC_5.1.md v2.2 (2026-08-24) already dynamizes SIM_target_percent off the same Table C field — that doc should also be tagged [CHR-49] (currently cites only "Client confirmed 2026-08-24", no CHR tag; flagged for a follow-up CHR-tag pass). | | 2026-09-03 | v21 | UC_2.3 §5 "Eval Requirement — Futures" / "Eval Requirement — Forex" rows | Source column "Fixed (no Zapier table to config)" — implied these SIM-side notional/contract values were hardcoded UI literals. | Source column corrected to Table B (Futures Configuration Matrix, Max_Contracts_ES_Equiv) and Table A (Forex Configuration Matrix, Max_Forex_Notional) respectively — same fields already cited for the "Live Capital Allocation — Futures/Forex" rows below, since SIM Eval Requirement and Live Capital Allocation read the identical Table A/B values for Levels 1/2/5 (only the SIM vs Live label differs, not the underlying data source). | User request, 2026-09-03. Consistent with the v19 fix already applied to the "Live Capital Allocation" rows (Source: Zapier Integration V7.pdf, Appendix A "Forex Configuration Matrix" / Appendix B "Futures Configuration Matrix"). |