Skip to main content

Source: ocean/docs/adr/0024-modularize-billing-mutations.md | ✏️ Edit on GitHub

ADR-0024: Modularize GraphQL Billing Mutations

Date: 2025-08-13

Status: Accepted

Context​

supabase/functions/graphql-v2/resolvers/billing/mutation-resolvers.ts had grown too large and monolithic, making code review and maintenance difficult. Team practice caps files around 400–450 lines for readability.

Decision​

Split billing mutations by concern and compose:

  • mutations/billing-details.ts: updateBillingDetails
  • mutations/subscription.ts: createSubscription, updateSubscription (with seat cap 5), cancelSubscription, resumeSubscription, createCheckoutSession
  • mutations/usage.ts: reportUsage
  • mutation-resolvers.ts: exports a merged object: { ...billingDetailsMutations, ...subscriptionMutations, ...usageMutations }

Consequences​

  • Smaller, focused modules are easier to test and review.
  • Clearer ownership by concern (billing details vs subscription vs usage).
  • Enables independent evolution without blowing up a single file.

Notes​

  • Seat cap logic remains enforced server-side in updateSubscription (1..5).
  • Trials remain removed per policy (Free until upgrade).