# 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.
