SRS: UC_8.2.10 — Flow 15B: Pod Leader Opt-In & Provisioning

---

1. UC Index

---

UC_8.2.10 — Flow 15B: Pod Leader Opt-In & Provisioning

---

2. Trigger

Event: Webhook received from the opt-in button click in the Pod_Leader_Invite email.

The Pod_Leader_Invite email is sent upstream by Flow 6 (L6 Transition / UC_8.1) when a trader's New_Level reaches Min_Pod_Leader_Level = 7 (sourced from Table C: Global_Variables).

PostgreSQL-native note: Pod_Leader_Registry ("Table E" in the original Zapier spec documentation) is built natively in PostgreSQL as the single source of truth — it is NOT a live Zapier Table. "Table E" is retained elsewhere in sourcing citations only as a naming/cross-reference convention to the original RFQ section. (Restates POD-JOIN-02.)

(Source: Zapier Integration V7.pdf §Flow 15B line 2041; §Table C line 217)

---

3. Pre-conditions

---

4. Post-conditions

---

5. Basic Flow

Step 1. Receive Webhook

• Zapier catches the opt-in webhook from the Pod_Leader_Invite email button.
• Opt-in is a single button click — no form is shown and no profile data is collected at this step. Trading_Style is collected only by the Step 7.1 Typeform; Asset_Class is never selected (inherited from Users.asset_class at Step 2).
• Payload contains: user_id, leader_name.

(Source: Zapier Integration V7.pdf §Flow 15B line 2041 — "button click in the Pod_Leader_Invite Email"; Client confirmation 2026-09-28 — Asset_Class inherit; Client confirmation 2026-09-25 — Trading_Style via Typeform; BA decision 2026-10-30 — no opt-in form)

Step 2. Insert into Pod_Leader_Registry

• Insert record into Pod_Leader_Registry (native PostgreSQL table) via SQL SELECT-INSERT to inherit asset_class directly from the Users table:
  • Leader_ID = user_id
  • Leader_Name = leader_name
  • Asset_Class — inherited from Users.asset_class (NOT from form input)
  • Trading_Style = NULL — written only at Step 7.1 (Typeform)
  • Is_Profile_Complete = FALSE
  • Status = 'Active'
  • Current_Count = 0
  • Pending_Carry_Balance = $0.00
  • Max_Capacity = 7 (from Table C Pod_Max_Capacity)
  • google_workspace_email — written here after Step 3 resolves (or updated in Step 3)

(Source: Zapier Integration V7.pdf §Flow 15B line 2042; Client confirmation 2026-09-28 — Asset_Class inherited from Users table)

Step 3. Provision Google Workspace Account

• Call Google Workspace Admin Directory API:
  • Endpoint: POST /admin/directory/v1/users
  • Key fields: primaryEmail = [firstname].[lastname]@stacktrading.com, orgUnitPath: /Pod Leaders, changePasswordAtNextLogin: true
  • Handle format: firstname.lastname@stacktrading.com (lowercase, no diacritics).
  • OU-level MFA enforced (Google Authenticator required before Workspace access — orgUnitPath = /Pod Leaders).
• Email collision handling (atomic loop): WHILE GET /users/{handle}@stacktrading.com → 200: append 1, 2, 3, ... until unique (e.g. john.doe1@stacktrading.com). Do NOT use user_id suffix or other patterns.
• Initiate Google Standard Invite Flow → activation link sent to personal user_email; no password generated or stored by Middleware.
• DB write:
  • UPDATE Users SET google_workspace_email = '{handle}@stacktrading.com'
  • UPDATE Pod_Leader_Registry SET google_workspace_email = '{handle}@stacktrading.com'

(Source: Client confirmation 2026-09-28 — Flow 15B Step 2)

Step 4. Pod_Leader_Registry & Discord Auto-Provisioning — Create Discord Channel

• Call POST /create-pod-channel:
  • Input: user_id, leader_name
  • Middleware slugifies the channel name before calling Discord Bot:
    • Convert to lowercase.
    • Replace spaces with hyphens.
    • Strip all Vietnamese accents and special characters.
    • To prevent name collisions between leaders who share the same name: append the first 4 characters of leader_id to the end of the slug. e.g. pod-john-doe-a7b2.
  • Discord Bot creates a private text and voice channel with the slugified name.
  • Sets permissions to assigned pod members.
  • Leader channel access (per-user permission): IF the leader's discord_user_id IS NOT NULL → Bot grants the leader access to the channel at creation. IF discord_user_id IS NULL → channel is still created; leader access is granted when the leader runs /link (BR_8.2.10.11). Access is never granted via the shared Pod Leader role.
  • Returns JSON: { "channel_id": "string", "channel_url": "URL_string" }
• Zapier waits for JSON response containing channel_url.

(Source: Zapier Integration V7.pdf §Flow 15B lines 2043–2045; RFQ_ Stack Trading Prop Tech V7.pdf §Create Pod Channel lines 2268–2280; Client confirmation 2026-09-20 — slugify + leader_id suffix)

Step 5. Write channel_url to User Profile

• Update SQL user record: write channel_url from Step 4 response to the trader's profile.

(Source: Zapier Integration V7.pdf §Flow 15B line 2046)

Step 6. Assign Discord Role

• Call POST /manage-discord-role:
  • Input: 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). The role and channel access are applied when the leader later runs /link (BR_8.2.10.11).

(Source: Zapier Integration V7.pdf §Flow 15B lines 2049–2050; BA decision 2026-10-30 — late-linking)

Step 7. Send Welcome Email

• Send Pod_Leader_Welcome email to trader's personal email (user_email — NOT @stacktrading.com).
• Content: welcome kit including:
  • @stacktrading.com Google Workspace account handle.
  • Google Workspace activation link (from Step 3).
  • Private Discord channel URL (channel_url).
  • Calendar access links.
  • Mandatory Typeform link for Trading Style profile setup (see Step 7.1): https://form.stacktrading.com/mentor-profile-setup?leader_id={{user_id}}&email={{user_email}} (Hidden Fields auto-injected for automatic user identification).

(Source: Zapier Integration V7.pdf §Flow 15B line 2051; §Email Templates line 768; Client confirmation 2026-09-28 — Step 4; Client confirmation 2026-09-25 — Typeform mandatory in Pod_Leader_Welcome)

Step 7.1. Pod_Leader_Registry Profile Sync — Trading_Style (Typeform Webhook)

• Trigger: New Entry Submitted from the Typeform linked in Step 7.
• Pod Leader declares:
  • Trading_Style — multi-select: Scalping, Day Trading, Swing Trading, Algorithmic Trading (required; no sub-details needed per client confirmation)
  • Asset_Class — displayed for reference only (pre-populated from Users.asset_class; read-only; Pod Leader cannot change it)
• Webhook fires from Typeform → Middleware (Zapier Flow 15B.1):

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

• Note: Asset_Class is NOT written from Typeform — it was already inherited from Users.asset_class at Step 2 insert. Typeform only confirms the display.
• Effect on Flow 10: Pod_Leader_Registry row becomes fully visible to the Mentee Matching Engine only after Is_Profile_Complete = TRUE is written. Until Step 7.1 completes, the Pod Leader is not matched with mentees.
• Trigger Flow 11 (Waitlist Processor): immediately after Is_Profile_Complete = TRUE is written, Middleware triggers Zap Flow 11: Waitlist Processor for this Leader_ID to fill the new pod's open slots from Pod_Waitlist (FIFO, same Asset_Class). This — not the Step 2 registry insert — is the "new leader" event of UC_8.2.8 BR_8.2.8.1 #2.

(Source: Client confirmation 2026-09-25 — Typeform mandatory in Pod_Leader_Welcome; Trading_Style multi-select; Asset_Class display-only)

---

6. Exceptional Flows

Exc-1 — POST /create-pod-channel returns error or timeout:

• channel_url not returned. Step 5 (DB write) and Step 6 (Discord role) cannot proceed.
• Confirmed behavior (Option A — Retry + Alert): Do NOT roll back the Pod_Leader_Registry DB entry inserted in Step 2. Middleware retries POST /create-pod-channel 3 times with exponential backoff. If all retries fail → SEV-1 Slack alert to #ops-it for Ops to manually create the channel and update channel_url in DB.
• Rationale: Flow 15B is triggered by a button click in an email — there is no active dashboard UI to display an error to. DB rollback would leave the trader in a broken state with no recovery path.
• (Source: Client confirmation 2026-10-07)

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

• Confirmed behavior (Option A — Proceed): Allow the flow to continue (Steps 4–7: create Discord channel, assign Discord role, send welcome email to personal email). Log WORKSPACE_PROVISIONING_FAILED error + send SEV-2 alert to #ops-it for Ops to manually provision the Workspace account later.
• After Ops manually provisions the Workspace account, a log entry is sufficient — Middleware does not need to 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-3 — discord_user_id is NULL when calling POST /manage-discord-role:

• Middleware drops Discord action and returns 200 OK.
• DB writes (Steps 2, 3, and 5) remain committed. Email (Step 7) still sends.
• (Source: RFQ_ Stack Trading Prop Tech V7.pdf §Manage Discord Role lines 2345–2350)

Exc-4 — Duplicate opt-in (trader clicks button twice):

• ⚠️ Idempotency behavior not specified in source. BA assumption: check Pod_Leader_Registry for existing Leader_ID before inserting; skip insert if record exists with Status = 'Active'. Response behavior (200 OK no-op vs 409 Conflict) pending dev confirmation.

---

7. Business Rules

BR_8.2.10.1: Min_Pod_Leader_Level sourced from Table C

The eligibility threshold for Pod Leader opt-in is Min_Pod_Leader_Level, read from Table C: Global_Variables. Current seed value = 7. This value must never be hardcoded in application logic — always read from Table C to allow configuration without a code deploy.

(Source: Zapier Integration V7.pdf §Table C line 217)

BR_8.2.10.2: Discord Channel Naming — Slugification + Collision Prevention

The channel name for each Pod Leader must be derived by slugifying leader_name:

1. Convert to lowercase.
2. Replace spaces with hyphens.
3. Strip all Vietnamese accents and special characters.
4. Append the first 4 characters of leader_id to prevent collisions when two leaders share the same name (e.g. pod-john-doe-a7b2).

This slugification must be executed by Middleware in POST /create-pod-channel before the Discord Bot API call.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Create Pod Channel lines 2273–2274; Client confirmation 2026-09-20)

BR_8.2.10.3: Current_Count Must Reflect Actual Assignments

Pod_Leader_Registry.Current_Count must be incremented each time a mentee is assigned to the leader (via Flow 10 Step 4). At provisioning (this flow), Current_Count is initialized to 0. Accuracy of this field is critical for the Flow 10 matching waterfall's capacity fallback logic.

(Source: Zapier Integration V7.pdf §Flow 10 Step 4 line 1828)

BR_8.2.10.4: Discord Resiliency — NULL discord_user_id

POST /manage-discord-role must return 200 OK when discord_user_id IS NULL. Flow must not crash. DB writes and email dispatch proceed regardless.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Manage Discord Role lines 2345–2350)

BR_8.2.10.5: Asset Class Must Match 100% — Cross-Asset Pod Leadership Not Allowed

A Pod Leader's Asset_Class (Futures or Forex) must exactly match the asset class of all mentees assigned to their pod. A Forex trader cannot be a Pod Leader for Futures traders, and vice versa. Flow 10's matching criteria enforces "Asset Match (Strict)" as the primary gate — capacity and style are only evaluated after asset class is confirmed.

(Source: Client confirmation 2026-09-20 — "Yes, the match must be 100% strict")

BR_8.2.10.6: Google Workspace Provisioning — Regular Pod Leaders

Every Regular Pod Leader provisioned via Flow 15B MUST receive a @stacktrading.com Google Workspace account. The account is created under orgUnitPath = /Pod Leaders. OU-level policy enforces MFA (Google Authenticator) before any Workspace access is granted — Middleware does not implement MFA logic directly.

• Handle format: firstname.lastname@stacktrading.com (lowercase, no diacritics).
• Collision resolution: append sequential index (1, 2, ...) via atomic loop (e.g. john.doe1@stacktrading.com).
• Activation link delivered to personal user_email via Google Standard Invite Flow. No password generated or stored by Middleware.
• google_workspace_email written to both Users table and Pod_Leader_Registry (native PostgreSQL table).

(Source: Client confirmation 2026-09-28 — Flow 15B Step 2 — Workspace provisioning)

BR_8.2.10.7: Asset_Class Inheritance — Regular Pod Leaders Must Not Re-Select

Regular Pod Leaders (Level 7+) must NOT be prompted to select Asset_Class anywhere in this flow. Asset_Class is automatically inherited from Users.asset_class at DB write time (Step 2) and is shown read-only on the Step 7.1 Typeform. This prevents mismatch between a trader's live trading asset class and their Pod identity.

Founding Mentors (Flow 1.5) are exempt from this rule — they may be external hires with no existing Users.asset_class record and therefore MUST declare Asset_Class explicitly via Typeform (UC_8.2.13 Step 9).

(Source: Client confirmation 2026-09-28)

---

BR_8.2.10.8: Typeform Profile Sync — Trading_Style Confirmation Required Before Flow 10 Matching

Every Regular Pod Leader provisioned via Flow 15B MUST complete the Typeform profile setup (Step 7.1) before becoming visible to the Flow 10 Mentee Matching Engine. Is_Profile_Complete is initialized to FALSE at Step 2 insert and set to TRUE only by the Typeform webhook write. Pod Leaders with Is_Profile_Complete = FALSE are excluded from Flow 10 matching queries.

Asset_Class is displayed in the Typeform for reference only — it is read-only and pre-populated from Users.asset_class. The Pod Leader cannot change Asset_Class via Typeform.

(Source: Client confirmation 2026-09-25 — Typeform mandatory for standard Pod Leaders too; Asset_Class display-only)

---

BR_8.2.10.9: Discord Channel Failure — No DB Rollback; Retry 3× Then SEV-1

If POST /create-pod-channel fails or times out, the Pod_Leader_Registry record inserted in Step 2 MUST NOT be rolled back. Middleware retries with exponential backoff (3 attempts). If all retries fail, fire SEV-1 alert to #ops-it for Ops to manually create the channel and update channel_url in DB. Flow 15B is triggered by email button click — there is no active dashboard to display an error to, making DB rollback an unrecoverable dead end.

(Source: Client confirmation 2026-10-07)

BR_8.2.10.10: Google Workspace Failure — Non-Blocking; Cascade Continues

If Google Workspace provisioning fails at Step 3, the flow MUST NOT halt. Steps 4–7 (Discord channel, Discord role, welcome email) proceed normally. Ops is notified via SEV-2 alert to #ops-it and provisions the Workspace account manually. After Ops provision, Ops triggers the native Google Workspace welcome email from the Google Admin console — Middleware does not send a secondary email.

(Source: Client confirmation 2026-10-07)

BR_8.2.10.11: Late-Linking — Pod Leader Role + Own Channel Access on /link

When a user runs /link and Pod_Leader_Registry has a row with Leader_ID = user_id AND Status NOT IN ('Terminated', 'Permanently_Ineligible'), the bot MUST (1) assign the Pod Leader role and (2) grant that user per-user access to their own pod channel (Users.channel_url). Pod channel access is never granted via the shared Pod Leader role, so a leader cannot see other pods. Same rule as UC_8.2.13 BR_8.2.13.27 (Founding Mentors). Runs together with level-title sync (UC_8.1.1) and Pod Member sync (UC_8.2.1 A-04). ⚠️ UC_8.1.1 (/link handler, BA owner Huyen Dinh) not yet updated with this branch.

(Source: QnA_Level_Promotion §3.3 late-linking principle, 2026-09-30; BA decision 2026-10-30 — channel access granted at link time)

---

7.1 Leave & Hiatus Policy for Regular Pod Leaders (Flow 13 Integration)

Cross-reference: UC_9.2 — Flow 13 (Time-Off Management) governs the full leave pipeline. This section documents the Pod Leader-specific rules that apply when Flow 13 processes a leave request for a Regular Pod Leader (Level 7+).

7.1.1 Leave Does Not Revoke Pod Leader Role

Valid leave approved via Flow 13 does NOT cancel the Pod Leader role. BPS Admin MUST NOT manually trigger POST /api/bps/mentor/terminate during an approved leave period.

All Pod resources are preserved during On_Leave status:

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-15] client confirmed 2026-10-30; [POD-XF-18] client sheet 2026-11-04)

7.1.2 Pod_Leader_Registry Status Matrix

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-16] client confirmed 2026-10-30; [POD-XF-18] client sheet 2026-11-04)

7.1.3 Carry Balance Behavior During Leave

Pending_Carry_Balance continues to accrue and vest normally during approved leave. The monthly vest run (Flow 17, 1st of month) MUST include records with Pod_Leader_Registry.Status = 'On_Leave' — no freeze, no skip. Carry is only frozen on Drawdown Defense suspension (UC_8.2.9 BR_8.2.9.3) or forfeited on Termination (Flow 15C).

(Source: QnA_STAGE6_POD_SYSTEM_FLOW10_11.md [POD-XF-18]; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-008] — client sheet 2026-11-04)

---

8. Data Model

Pod_Leader_Registry (native PostgreSQL table) — new record at opt-in

(Source: Zapier Integration V7.pdf §Table E lines 777–790 — naming reference only; Pod_Leader_Registry is native PostgreSQL, see §2 Trigger note)

---

9. API Reference

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Create Pod Channel; §Manage Discord Role)

---

10. Email Templates

(Source: Zapier Integration V7.pdf §Email Templates line 768)

---

11. Acceptance Criteria

---

12. Changelog