arthur/xtablo-source
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions 7

docs: add pricing signup flow verification design spec

Browse source
This commit is contained in:
Arthur Belleville 2026-03-15 18:35:02 +01:00
parent ca4ede28bb
commit 3d4297f330
No known key found for this signature in database
1 changed files with 127 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
docs/superpowers/specs/2026-03-15-pricing-signup-three-plan-happy-path-verification-design.md Normal file
View file

@ -0,0 +1,127 @@
# Pricing Signup Flows (Solo, Team, Founder) Happy-Path Verification - Design
Date: 2026-03-15
Status: Approved in brainstorming session (user confirmations captured in chat)
## 1) Problem and Outcome
We need to verify that the pricing signup flow works correctly for three plans:
- `solo` (monthly)
- `team` (monthly)
- `founder` (yearly)
Expected product behavior:
- All three plans require card details at signup (immediate Stripe Checkout handoff).
- `solo` and `team` create monthly subscriptions.
- `founder` creates a yearly subscription.
Desired outcome of this verification cycle:
- Confirm all three happy paths work end-to-end in Stripe test mode.
- Produce clear evidence for each path (redirects, success return, final subscription cadence in app and billing data).
## 2) Current Context (Observed in Codebase)
Current code currently exposes signup intent as `trial` or `founder` in `apps/main/src/pages/signup.tsx` and `apps/main/src/hooks/auth.ts`, while checkout API supports `solo`, `team`, and `founder` in `apps/api/src/routers/stripe.ts`.
This verification scope therefore validates the target intended behavior (3-plan immediate checkout) and is expected to surface any mismatches between signup wiring and checkout capabilities.
## 3) Scope
### In scope
- Live Stripe test-mode happy-path verification.
- Three independent signup runs:
- `solo` monthly
- `team` monthly
- `founder` yearly
- End-to-end checkpoints from signup submission to post-payment app state.
- Evidence capture per flow.
### Out of scope
- Declined cards and other payment failures.
- Checkout cancellation path.
- Webhook delay/retry/failure behavior.
- Automation framework creation (Playwright/Cypress) in this cycle.
## 4) Verification Architecture
The verification work is organized into small, independent units:
1. **Environment Readiness Unit**
- Confirms local app/API are running with Stripe test credentials and webhook forwarding.
- Provides a go/no-go decision before starting flows.
2. **Plan Execution Unit**
- Executes each plan flow independently with a unique test user.
- Uses a standardized runbook so all plans are evaluated with identical checkpoints.
3. **Outcome Validation Unit**
- Validates post-checkout state in two layers:
- UI layer: selected plan reflected to the user.
- Billing layer: active subscription interval (`month` vs `year`) and expected plan mapping.
4. **Evidence and Reporting Unit**
- Captures screenshots, URLs reached, and final observed billing values.
- Produces a concise pass/fail matrix across the three plans.
These units are intentionally decoupled so each one can be re-run without restarting the whole process.
## 5) Data Flow to Verify (Per Plan)
For each of `solo`, `team`, `founder`:
1. Open signup and select plan.
2. Submit valid user form with a unique test email.
3. Confirm immediate redirect to Stripe Checkout.
4. Enter Stripe test card (`4242 4242 4242 4242`) and complete payment.
5. Confirm return to app success URL.
6. Verify plan/cadence outcome:
- `solo` => active paid subscription, monthly interval.
- `team` => active paid subscription, monthly interval.
- `founder` => active paid subscription, yearly interval.
## 6) Validation Signals and Evidence
Per plan, collect:
- Signup plan selection confirmation.
- Checkout page reached (URL and screenshot).
- Success return URL reached (URL and screenshot).
- In-app billing state screenshot.
- Billing data point showing active subscription interval (month/year).
Recommended reporting structure:
- `plan`
- `checkout reached`
- `payment completed`
- `success redirect`
- `in-app plan state`
- `interval expected`
- `interval observed`
- `result`
- `notes`
## 7) Error Handling During Happy-Path Runs
Even in happy-path-only scope, verification should stop and report clearly when a blocking issue appears:
- If checkout redirect does not happen after signup, mark the flow as failed and do not force workarounds.
- If payment succeeds but app state does not update, mark as failed and log whether webhook or sync appears delayed.
- If interval does not match expected cadence, mark as failed and capture exact observed value.
No failure-path debugging is expanded in this phase; we only capture enough detail to hand off targeted fixes.
## 8) Test Data Strategy
- Use one fresh user per plan with timestamped email aliases.
- Keep runs isolated so one failed flow does not contaminate others.
- Avoid reusing pre-existing subscriptions for this phase.
## 9) Acceptance Criteria
Verification is successful when all conditions are true:
1. `solo` flow reaches checkout at signup, completes payment, and results in monthly active subscription.
2. `team` flow reaches checkout at signup, completes payment, and results in monthly active subscription.
3. `founder` flow reaches checkout at signup, completes payment, and results in yearly active subscription.
4. Evidence is recorded for each flow with enough detail to reproduce or diagnose.
## 10) Next Step After This Design
After spec approval, create an implementation/execution plan for running the live verification and, if needed, patching signup wiring so all three plans trigger immediate checkout.