SRS: UC_8.2.13 — Flow 1.5: Founding Mentor Initialization

---

1. UC Index

---

UC_8.2.13 — Flow 1.5: Founding Mentor Initialization

---

2. Trigger

Event: Webhook received from Signwell — event type: Document Signed (Founding Pod Leader Agreement).

Rippling is not used as the contract execution platform for this flow. Signwell replaces Rippling for the purpose of contract signing and webhook trigger. Founding Mentors may be from any country — nationality is not a constraint for eligibility.

(Source: Zapier Integration V7.pdf §Flow 1.5 lines 1009–1010; Client confirmation 2026-09-20 — "We are replacing Rippling with Signwell for contract execution")

---

3. Pre-conditions

---

4. Post-conditions

---

5. Basic Flow

Step 1. Receive Signwell Webhook [CHR-78]

• Zapier catches the Signwell webhook: document_completed — Founding Pod Leader Agreement.
• Payload contains: user_email of the signer.
• Middleware validates HMAC-SHA256 signature before any processing (BR_8.2.13.10).

(Source: Zapier Integration V7.pdf §Flow 1.5 lines 1009–1010; Client confirmation 2026-09-20)

Step 2. Upsert Global_User_ID [CHR-78]

• Query PostgreSQL for existing record by user_email.
• If no record exists: generate new Global_User_ID.
• Upsert the record with:
  • Role_Flag = 'Founding_Mentor'
  • is_pod_leader = TRUE
  • contract_pod_leader = 'Signed'
• All existing fields (trade history, challenge status, etc.) are preserved — no duplicate row is ever created.

(Source: Zapier Integration V7.pdf §Flow 1.5 Action 2 lines 1013–1015; Client confirmation 2026-09-21)

Step 3. Smart Gating — KYC Dispatch [CHR-78]

• Check identity_status on the upserted record:
  • Brand new user OR identity_status != 'Approved': Call Veriff API POST /v1/sessions → get { "sessionId": "string", "verification_url": "URL" }. Send KYC initiation email with verification_url. Set identity_status = 'Pending'.
  • Existing trader with identity_status = 'Approved': Skip Veriff entirely — KYC already verified (smart gate bypass).

(Source: Zapier Integration V7.pdf §Flow 1.5 Action 1 line 1012; Client confirmation 2026-09-22 — same KYC→Payouts sequence as Stage 3)

Step 4. Smart Gating — Dots Payout Dispatch [CHR-78]

• Check payout_status on the upserted record:
  • payout_status != 'Approved' AND dots_payee_id IS NULL: Dispatch Dots payout setup link to user_email for banking + W-9/W-8BEN registration.
  • payout_status = 'Approved' OR dots_payee_id IS NOT NULL: Skip Dots — payout profile already configured (smart gate bypass).
• Steps 3 and 4 are independent — partial bypass is valid (e.g., bypass KYC only, or bypass Dots only).

(Source: Client confirmation 2026-09-22 — Flow 1.5 uses KYC→Payouts sequence identical to Stage 3 Live Onboarding)

Step 5. Provisioning Gate [CHR-78]

• Middleware checks: identity_status = 'Approved' AND payout_status = 'Approved'.
• Case A — One or both statuses still Pending (async): Middleware registers as an async webhook listener. Gate opens when BOTH Veriff callback (identity_status = 'Approved') AND Dots callback (payout_status = 'Approved') are received. Steps 6–8 do not execute until both are received.
• Case B — Both statuses already Approved (synchronous): Gate evaluates to TRUE immediately after Steps 3 and 4 complete (both smart gate bypasses fired). Middleware does NOT wait for any webhook — fires Steps 6–8 immediately.
• Either condition alone does not trigger provisioning.

(Source: Client confirmation 2026-09-22)

Step 6. Provision Google Workspace Account [CHR-78]

• Call Google Workspace Admin Directory API:
  • Endpoint: POST /admin/directory/v1/users
  • Key fields: primaryEmail = [firstname].[lastname]@stacktrading.com, orgUnitPath: /Founding Mentors, changePasswordAtNextLogin: true
  • OU-level MFA enforced (Google Authenticator required before Workspace access)
• Email collision handling (atomic loop): WHILE GET /users/{handle}@stacktrading.com → 200: append .1, .2, .3, ... until unique.
• Initiate Google Standard Invite Flow → activation link sent to personal email; no password generated or stored by Middleware.
• UPDATE Users SET google_workspace_email = '{handle}@stacktrading.com'

(Source: Zapier Integration V7.pdf §Flow 1.5 Action 3 lines 1016–1025; Client confirmation 2026-09-18/20)

Step 6.5. Create Discord Pod Channel [CHR-78]

• Call Middleware endpoint POST /create-pod-channel with:
  • user_id: Founding Mentor's Global_User_ID
  • leader_name: extracted from google_workspace_email — strip @stacktrading.com suffix (e.g. john.doe@stacktrading.com → john.doe). Write leader_name = 'john.doe' to Pod_Leader_Registry.Leader_Name (Table E).
• Middleware slugifies the channel name before calling Discord Bot — same rule as Flow 15B (BR_8.2.10.2):
  • Convert to lowercase; replace spaces and . with hyphens; strip all accents and special characters.
  • Append the first 4 characters of leader_id (e.g. john.doe → pod-john-doe-a7b2).
• Discord Bot creates a private text and voice channel with the slugified name and sets permissions to assigned pod members.
• Leader channel access (per-user permission): IF discord_user_id IS NOT NULL → Bot grants the Founding Mentor access to the channel at creation. IF discord_user_id IS NULL → channel is still created; leader access is granted when the mentor runs /link (BR_8.2.13.27). Access is never granted via the shared Pod Leader role.
• Returns JSON: { "channel_id": "string", "channel_url": "URL_string" }. Zapier waits for the response containing channel_url.
• leader_name MUST be derived from the Workspace handle, NOT from Veriff legal_name (see BR_8.2.13.17).
• This step executes immediately after Step 6 (Workspace provisioning) and before Step 7 (Amplify coupon generation).
• On failure: Retry 3× with exponential backoff; no rollback of Pod_Leader_Registry; SEV-1 alert if all retries fail. Steps 7 and 8 proceed regardless. See Exc-5.

(Source: Client supplement 2026-10-19 — leader_name source; RFQ_ Stack Trading Prop Tech V7.pdf §Create Pod Channel; BA decision 2026-10-29 — align slug, response and failure handling with Flow 15B / UC_8.2.10; BA decision 2026-10-30 — leader channel access granted at link time)

Step 6.6. Write channel_url to User Profile

• Update SQL user record: write channel_url from Step 6.5 response to the Founding Mentor's profile.

(Source: Zapier Integration V7.pdf §Flow 15B line 2046 — applied to Flow 1.5 per BA decision 2026-10-29)

Step 6.7. Assign Discord Role

• Call POST /manage-discord-role with user_id, add_role = 'Pod Leader'.
• If discord_user_id IS NULL → endpoint returns 200 OK and drops the action (BR_8.2.10.4). Flow continues.
• The skipped role and channel access are applied when the mentor later runs /link (BR_8.2.13.27).

(Source: Zapier Integration V7.pdf §Flow 15B lines 2049–2050 — applied to Flow 1.5 per BA decision 2026-10-29)

Step 7. Generate Amplify 100% coupon (EVAL_L1 only) [CHR-78]

• Generate 100% discount Amplify coupon restricted to EVAL_L1 (Associate Track, $650 — cannot apply to Reset, Accelerated, Advanced, or Live fees).

(Source: Zapier Integration V7.pdf §Flow 1.5 Action 4 lines 1017–1020; Client confirmation 2026-09-20)

Step 7.5. Discord Link Token

• IF discord_user_id IS NOT NULL → skip; no token needed (already linked).
• ELSE IF discord_link_token IS NOT NULL (existing trader, not yet linked) → reuse the existing token. Do NOT regenerate.
• ELSE → generate UUID, UPDATE Users SET discord_link_token = '{uuid}'.
• Runs after the provisioning gate, before Step 8. Not blocked by a Step 6.5 failure.
• The token is never overwritten by later steps, including checkout [CHR-91] when the mentor uses the coupon (BR_8.2.13.28).

(Source: BA decision 2026-10-30 — Founding Mentor receives Discord token in welcome email; QnA [DL-EP-02] single-use, no regeneration; QnA [DL-BIZ-04] skip token when already linked)

Step 8. Send Pod_Founding_Leader_Welcome email [CHR-78]

• To: user_email (personal email — NOT @stacktrading.com)
• Contains:
  • The 100% Amplify coupon code.
  • The Google Workspace activation link (from Step 6).
  • Onboarding instructions.
  • A Typeform link for profile setup (see Step 9): https://form.stacktrading.com/mentor-profile-setup?leader_id={{user_id}}&email={{user_email}} (Hidden Fields auto-injected).
  • Discord block (only when discord_user_id IS NULL): Discord invite URL + instruction "Join the server and type /link [discord_link_token] in #verify" with the token from Step 7.5.
  • Not included: Veriff KYC link (sent separately in Step 3), any Workspace password.
• Mentor uses coupon on public checkout ($0.00) → Level 0 SIM, standard starting capital. No BPS Admin manual provisioning.

(Source: Zapier Integration V7.pdf §Flow 1.5 Action 4 lines 1017–1020; Client confirmation 2026-09-28)

Step 9. Table E Profile Sync — Asset_Class & Trading_Style (Typeform Webhook) [CHR-145]

• Trigger: New Entry Submitted webhook from the Typeform linked in Step 8 — async, fires independently after mentor completes the profile form.
• Founding Mentor declares:
  • Asset_Class — Futures or Forex (required; Founding Mentors may be external hires without an existing Users.asset_class record)
  • Trading_Style — multi-select: Scalping, Day Trading, Swing Trading, Algorithmic Trading
• Webhook fires from Typeform → Middleware (Zapier Flow 1.5.1):

  UPDATE Pod_Leader_Registry
  SET
      Asset_Class         = '{{typeform.asset_class}}',
      Trading_Style       = '{{typeform.trading_style}}',
      Is_Profile_Complete = TRUE,
      Status              = 'Active',
      Updated_At          = NOW()
  WHERE Leader_ID = '{{typeform.leader_id}}';

• Effect on Flow 10: Pod_Leader_Registry row becomes visible to the Mentee Matching Engine only after this step writes a non-null Asset_Class. Until Step 9 completes, the Founding Mentor is not available to receive mentee assignments.
• Trigger Flow 11 (Waitlist Processor): immediately after the profile write succeeds (Status = 'Active' AND Is_Profile_Complete = TRUE), Middleware triggers Zap Flow 11: Waitlist Processor for this Leader_ID so open slots (Current_Count < Max_Capacity) are filled from Pod_Waitlist (FIFO, same Asset_Class). Fires once per Typeform submission; a re-submission that does not change Is_Profile_Complete from FALSE to TRUE does not re-trigger. This is the "new leader" event of UC_8.2.8 BR_8.2.8.1 #2 for Founding Mentors.
• Effect on Checkout [CHR-145]: Pod_Leader_Registry.Asset_Class becomes the required asset class when the Founding Mentor checks out with the 100% coupon. At checkout Step 5 (email onBlur), the cart asset_class must match Pod_Leader_Registry.Asset_Class and the cart product_id must be EVAL_L1; otherwise checkout is blocked and the mentor must re-select. If Step 9 has not been completed (Asset_Class IS NULL), checkout is blocked until the Typeform is submitted. See BR_8.2.13.25 / BR_8.2.13.26 (banners BN-18/19/20).

(Source: Client confirmation 2026-09-28 — Flow 1.5 Step 8, Table E Sync; client supplement 2026-10-20)

---

6. System-Level: Founding Mentor Defense Bypass (Continuous)

This is not a Zapier flow step — it is a continuous server-side protection rule activated by Role_Flag = 'Founding_Mentor'.

Logic: Any Global_User_ID with Role_Flag = 'Founding_Mentor' is protected via a system variable from automated suspension triggers (e.g., Drawdown Defense) that would otherwise impact their mentorship status.

This protection persists as long as Role_Flag = 'Founding_Mentor' is set on the record.

Carry balance during suspension: This scenario does not apply to Founding Mentors. Because the Defense Bypass rule exempts Founding Mentors from automated suspension triggers, their Pending_Carry_Balance is never automatically frozen by Drawdown Defense or DTO/Hiatus events. (Note: For standard Pod Leaders, Pending_Carry_Balance is temporarily frozen on hold until they return from suspension.)

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Task: Founding Mentor Defense Bypass lines 3141–3145; Client confirmation 2026-09-30 — carry balance freeze N/A for Founding Mentors)

---

6.1 Hiatus & Leave Governance (Flow 13 Integration)

Cross-reference: UC_9.2 — Flow 13 (Time-Off Management) governs the full leave processing pipeline. This section captures the Founding Mentor-specific rules that apply when Flow 13 is invoked for a Founding Mentor.

6.1.1 Absolute Role Preservation Principle

Temporary leave (DTO or Hiatus via Flow 13) MUST NOT be treated as role abandonment for a Founding Mentor. All administrative privileges and resources below are preserved 100% for the duration of On_Leave state:

Carry during leave is the same for Founding Mentors and standard Pod Leaders: no Pod Leader's Pending_Carry_Balance is frozen during approved leave — it keeps vesting via Flow 17. (Supersedes the earlier wording where the table said "Frozen" and this paragraph said "exempted entirely".)

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15] client confirmed 2026-10-30; [POD-XF-18] client sheet 2026-11-04; RFQ_ Stack Trading Prop Tech V7.pdf §Founding Mentor Defense Bypass)

---

7. Exceptional Flows

Exc-0 — Duplicate document_id webhook received (Step 1):

• Idempotency check: if contract_pod_leader = 'Signed' already exists for this user_email → HTTP 200 No-Op; warning logged. No duplicate upsert, KYC dispatch, or provisioning.

Exc-1 — Veriff session creation fails (Step 3):

• POST /v1/sessions returns non-200.
• 3 retries with exponential backoff (30s → 5min → 15min); after all fail: HALT — provisioning deferred. SEV-2 → #dev_ops.

Exc-2 — Global_User_ID already exists with a different Role_Flag (Step 3):

• Middleware matches by email and applies the upsert: Role_Flag = 'Founding_Mentor', is_pod_leader = TRUE, contract_pod_leader = 'Signed'. All other fields are preserved on the same Global_User_ID — no new row is created.
• Sub-case A — existing account is Active_Challenge or Active_DMA: Role_Flag = 'Founding_Mentor' is applied immediately; the existing trading account continues normally. If the mentor attempts to use the 100% Amplify coupon to purchase an additional account at checkout, the system blocks the purchase and returns: "You already have an active account."
• Sub-case B — existing account is Failed or Terminated: Role_Flag = 'Founding_Mentor' is applied. When the mentor uses the 100% coupon at the public checkout with their registered email, the system archives the previous failed/terminated account history to user_account_history, resets metrics, and provisions a new SIM challenge under the same Global_User_ID.

Exc-3 — Google Workspace provisioning fails (Step 6):

• Confirmed behavior (Option A — Proceed): Allow the flow to continue with Steps 7 and 8 (Amplify coupon generation and Pod_Founding_Leader_Welcome email to personal email). Log WORKSPACE_PROVISIONING_FAILED error + send SEV-2 alert to #ops-it for Ops to manually provision/re-sync the Google Workspace account later.
• After Ops manually provisions the Workspace account, a log entry is sufficient — Middleware does not send a secondary email. Ops triggers the native Google Workspace welcome email directly from the Google Admin console.
• (Source: Client confirmation 2026-10-07)

Exc-4 — Amplify coupon generation fails (Step 7):

• Confirmed behavior (Option A — Hold email): Hold the Pod_Founding_Leader_Welcome email; do not send without the coupon. Alert #ops-it to generate the coupon manually; resend email once coupon is ready.
• Rationale: the primary value of the welcome email is delivering the 100% coupon — sending without it generates immediate support tickets.
• Note: Founding Mentor Amplify coupons have no hard TTL/expiry (Retention coupons from Flow 7B have 10-day expiry, but not these).
• (Source: Client confirmation 2026-10-07)

Exc-5 — Discord pod channel creation fails (Step 6.5):

• POST /create-pod-channel returns non-200 or connection timeout.
• channel_url not returned → Step 6.6 (DB write) and Step 6.7 (Discord role) cannot proceed.
• Behavior (same as UC_8.2.10 Exc-1): Do NOT roll back the Pod_Leader_Registry record. Middleware retries POST /create-pod-channel 3 times with exponential backoff. If all retries fail → log DISCORD_CHANNEL_CREATION_FAILED with user_id and leader_name + SEV-1 Slack alert to #ops-it; Ops creates the channel manually and updates channel_url in DB (BR_8.2.13.29).
• Steps 7, 7.5 and 8 proceed regardless. Do NOT hold the welcome email.

---

8. Business Rules

Users Table (relevant fields added/updated by this flow)

(Source: Client confirmation 2026-09-21 — contract_pod_leader field confirmed; distinct from contract_status which is reserved for Trader ICA in Flow 3E)

Pod_Leader_Registry Table E — fields written by this flow

---

10. API Reference

(Source: Client confirmation 2026-09-18; Zapier Integration V7.pdf §Flow 1.5)

---

11. Email Templates

(Source: Zapier Integration V7.pdf §Flow 1.5 lines 1017–1020)

---

12. Acceptance Criteria

---

13. Changelog