# RFC: {Feature Name}

**Date:** YYYY-MM-DD  
**Author(s):** [name(s)]  
**Status:** Draft → Review → Approved → Implemented → Complete  
**Decision:** [TBD initially]

---

## Summary

One paragraph: what problem are we solving? Why now?

Example:
> Stripe's latest API requires us to migrate from `stripe.charges.*` to `stripe.payments.*`. 
> This affects payout batching (current: single transfer per batch; new: batch transfers = group pending creators by region). 
> Window to migrate: 3 months (deadline June 28, 2026) before old API deprecated.

---

## Problem Statement

**Current State:**
- What's not working today? Specific pain points + evidence (metrics, user feedback, etc.)
- Example: "Payout execution time is 8 min; creators expect < 5 min. SLA target: 99.9% success rate; current: 99.2%."

**Why Now:**
- What changed? Why is this urgent?
- Example: "Stripe deprecated charges API (deadline June 28); new payments API has batch transfer feature (fix our latency issue)."

---

## Proposed Solution

**High-Level Approach:**
- What's the core idea? (1–3 paragraphs)
- What won't we do? (important: be clear about non-goals)

**Detailed Design:**

### Component 1: [Name]
- What does this do?
- How does it interact with existing systems?
- Schema changes (if any)
- New endpoints (if any)
- Example code snippet (if helpful)

### Component 2: [Name]
- (Same structure as Component 1)

**Key Decisions & Tradeoffs:**

| Option | Pros | Cons | Recommendation |
|--------|------|------|---|
| Option A | Pro1, Pro2 | Con1, Con2 | If [condition], choose A |
| Option B | Pro1 | Con1, Con2, Con3 | ⬅️ Recommended if [reason] |
| Option C | Simplest | Doesn't scale | Not recommended |

---

## Impact Analysis

**Who is affected (by role):**
- [ ] Core engineers (implementation)
- [ ] Creator ops (if monetization change)
- [ ] Designers (if user-facing)
- [ ] Data analysts (if instrumentation changes)
- [ ] Security/compliance (if auth/PII changes)

**Breaking Changes:**
- Is this backward compatible? (ideal: yes)
- If not, what's the migration path?
- How long do we support the old API? (concurrent mode?)

**Risk Assessment:**

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|-----------|
| Payout failure during migration | Medium | High (creators don't get paid) | Run migrations on staging first; parallel mode (old + new API) for 1 week |
| Data loss (incomplete batch history) | Low | High | Backup existing batch records before migration |
| Performance regression | Low | Medium | Benchmark batch transfer latency before/after |

---

## Metrics & Success Criteria

**Before** (current state):
- Payout execution time: 8 min
- Payout success rate: 99.2%

**After** (expected, Phase C):
- Payout execution time: ≤ 5 min
- Payout success rate: 99.9%

**How We'll Measure:**
- PostHog dashboard: `payout_batch_execution_duration_seconds`
- Sentry: `payout_transfer_failed` errors
- Weekly revenue integrity report

---

## Implementation Plan

**Phase 1: Preparation (May 5–12)**
- [ ] Set up staging environment with new Stripe API
- [ ] Build parallel-mode client (can call old + new API)
- [ ] Write tests for batch transfer logic
- [ ] Security review (PII in transfer data?)

**Phase 2: Pilot (May 15–19)**
- [ ] Deploy parallel mode to staging; test with prod-like data
- [ ] Test recovery scenario (one batch transfer fails; does backup succeed?)
- [ ] Load test: 100 simultaneous batch transfers

**Phase 3: Production Rollout (May 22–26)**
- [ ] Deploy parallel mode to production (no visible changes yet)
- [ ] Run both APIs for 1 week (shadow mode)
- [ ] Toggle over to new API only (May 26); keep old API as fallback
- [ ] Monitor for 1 week (SLO = zero incidents)
- [ ] Remove old API code (May 31)

**Rollback Plan:**
- If issues arise, switch back to old API (1-minute toggle)
- Restore from database backup if data corruption detected

---

## Alternatives Considered

**Alternative 1: Delay Migration**
- Pro: More time to plan
- Con: Stripe deadline is June 28; if we delay, we rush in final week
- Decision: Not recommended; start now

**Alternative 2: Manual Payout Processing**
- Pro: Simpler; no need to integrate new API
- Con: Not scalable; requires ops person to manually create transfers
- Decision: Not recommended; we have too many creators

---

## Open Questions

- [ ] Can we request SLA from Stripe on batch transfer latency? (We expect < 100ms)
- [ ] Are batch transfers in trial mode, or do we need prod setup?
- [ ] Do failed batch transfers trigger webhook? (Needed for DLQ)

---

## Review & Approval

| Role | Status | Notes |
|------|--------|-------|
| Tech Lead | ⬜ Pending | Need to confirm parallel mode approach |
| Product Lead | ⬜ Pending | Need to confirm scope (batch transfers only?) |
| Security Lead | ⬜ Pending | PII risk review on transfer data |
| Engineering Manager | ⬜ Pending | Resource allocation; sprint capacity |

**Comment Thread:**
- @tech-lead: LGTM on parallel mode; adds 10% overhead but safe. Can we run staging pilot May 10? (Tech Lead)
- @product-lead: Approve scope. One follow-up: can creators batch multiple videos into one payout? (e.g., deposit once per week instead of daily?) (Product Lead)
  - @author: Good idea; deferred to Phase C (would need UI redesign + creator education). Added as Phase C initiative. (Author)

---

## Decision

**Approved:** May 1, 2025, 10am UTC by [Tech Lead + Product Lead]

**Approved with conditions:**
- (if any)

**Rejected:** (if not approved; note reason)

---

## Implementation Tracking

- [ ] PR #1234: Parallel mode client + tests (Author Name)
- [ ] PR #1235: Batch transfer logic + instrumentation (Author Name)
- [ ] PR #1236: Staging migration + validation (Author Name)
- Deployment: May 22 (Target Envoy: Production)

---

## Resolution & Learnings (Post-Implementation)

**Completed:** May 31, 2026

**Actual Metrics:**
- Payout execution time (post): 4.2 min ✅ (beat target of 5 min)
- Payout success rate (post): 99.87% ✅ (met 99.9% target)

**Unexpected Challenges:**
- Stripe batch transfer had 500ms init delay; optimized via connection pooling
- One creator with 500+ pending transfers caused timeout; added cursor pagination

**Lessons Learned:**
- Parallel mode added safety; worth the 10% overhead
- Staging pilot caught edge case (timeout); saved us from production incident
- Rollback plan was never needed; confidence gave ops team peace of mind

---

## Template End

Template sections to include in RFC:
- [ ] Summary (1 paragraph)
- [ ] Problem statement (current + why now)
- [ ] Proposed solution (high-level + detailed)
- [ ] Impact analysis (who is affected + risks)
- [ ] Metrics & success criteria
- [ ] Implementation plan (phases + rollback)
- [ ] Alternatives considered
- [ ] Open questions
- [ ] Review & approval (roles + comments)
- [ ] Decision (approved/rejected + conditions)
- [ ] Implementation tracking (PRs + deployment)
- [ ] Resolution (post-implementation learnings)

# Design Handoff: [Feature Name]

**Figma Link:** [link to approved design]  
**Status:** Ready for development [date]

## Components

### Component 1: Subscribe Button
- Size: 44px height (desktop), 48px (mobile — touch target)
- Background: `primary` token = #FF006B
- Text: `caption-link` size = 14px weight 500
- States: default, hover (darker: #E6005F), active, disabled, loading
- Icon: $4.99 badge (if needed)

### Component 2: Success Toast
- Position: Top-right, 24px safe area
- Animation: Slide-in 200ms ease-out
- Duration: 3 seconds auto-dismiss
- Accessible: role="alert", announce via aria-live

## Responsive Breakpoints
- Mobile (375px): Full width, stack vertically
- Tablet (768px): Side by side
- Desktop (1280px+): Fixed layout

## Accessibility Notes
- All buttons tested in axe.core; 0 violations
- Contrast ratio: 4.8:1 (exceeds 4.5:1 AA requirement)
- Focus indicators: 2px solid #8F5FFF (secondary color)
- Color not sole indicator: Lock icon + red + text

## Implementation Notes
- Reuses Button + Toast components from design system
- New: `primary-button` Tailwind class (can be extracted to shared)
- No new fonts; all typography uses existing scale

rfcs/
├── 2026-05-01-stripe-batch-transfers.md       (Approved)
├── 2026-05-03-creator-onboarding-redesign.md  (In Review)
├── 2026-05-05-season-2-content-strategy.md    (Draft)
├── TEMPLATES/
│   ├── RFC_TEMPLATE.md
│   └── DESIGN_REVIEW_CHECKLIST.md
└── ARCHIVE/
    └── 2026-04-20-video-preload-strategy.md   (Rejected; replaced by different approach)