​

Billing architecture

​

How it works

await paymentProcessor.syncPendingProductDowngradeScheduledQuantity(
  {
    subscription: currentSubscription,
    downgradeRequest: pendingProductDowngrade,
    organization: organizationEntity,
    requestedSeatQuantity: quantity,
    transaction,
  },
  tools,
);

​

Trial schedule ownership decisions

• Owner: create/update/cancel trial schedules and persist trial_requests.
• Non-owner GraphQL: auth + validation + delegation.
• Non-owner webhooks: reconcile status transitions and complete/cancel rows.

​

Phased trials: onboarding vs Super Admin retrial

• Org-onboarding SKU: at most one products row may set onboarding_trial JSON (time_unit + time_amount). New org onboarding (apps/backend/src/utilities/subscription.ts → createDefaultSubscription) attaches a phased subscription schedule using that SKU’s duration metadata when eligible.
• Super Admin retrial (setOrganizationTrial): SKU must satisfy phasedTrialEligibleProduct and cannot equal the subscription’s current product (trialProductMatchesSubscriptionProduct — see apps/backend/src/utilities/trials.ts). When the SKU is not the onboarding-designated row, pass trialPhaseTimeUnit + trialPhaseTimeAmount; otherwise onboarding JSON resolves duration automatically (resolveTrialPhaseDurationSeconds).
• Stripe is authoritative — if webhook payloads disagree with Postgres, reconciliation updates local trial rows to match Stripe, with drift logged.

​

Pending downgrade overlap vs nominal post‑trial fallback

​

Extending this system

1. Add/extend the payment processor contract in apps/backend/src/tools/paymentProcessor/stripe/types.ts (example: syncPendingProductDowngradeScheduledQuantity).
2. Implement the method in the Stripe adapter at apps/backend/src/tools/paymentProcessor/stripe/ (example: syncPendingProductDowngradeScheduledQuantity.ts updates the schedule in-place and persists changed_to_quantity).
3. Call the adapter from the GraphQL boundary in apps/backend/src/gql/mutations/updateManualQuantity.ts (it fetches the pending downgrade row with lock: transaction.LOCK.UPDATE and then calls syncPendingProductDowngradeScheduledQuantity).
4. Verify reconciliation in the webhook consumer in apps/backend/src/tools/queue/consumers/stripeWebhookConsumer/customerSubscriptionUpdated.ts (it reads downgradeRequest.changed_to_quantity and matches Stripe line items).
5. Run backend verification:

make test module=backend

​

What not to do

​

File conventions

​

1. Overview

​

High-level summary

• Exposes GraphQL for billing UI flows (preview, checkout session, payment confirmation, downgrades, manual quantity).
• Uses tools.paymentProcessor as the only gateway to Stripe (create/update subscriptions, payment intents, invoices, products, etc.).
• Reconciles Stripe → Postgres via a queued Stripe webhook consumer plus customer.subscription.updated for ongoing sync (quantity, status, cycle dates, scheduled downgrades).
• Derives feature access from the org’s active subscription’s product via product_roles_scopes → scopes (not a separate “entitlements” service)—one-off products are for commerce, not a second parallel RBAC tree.

​

Product vs Price

• product_id — which plan the org selected (internal products.id)
• price_id (optional) — which price row bills them; pins grandfathered rates when a price is retired

​

Single currency (no multi-currency migrations)

​

External IDs and swappable processors

• New sales / catalog reads: resolve the active default Stripe Price id via getStripePriceIdForProduct(product) / getActiveDefaultPrice.
• Existing subscriptions: resolve via getActivePriceForSubscription(subscription) — uses pinned price_id when set (including retired rows), otherwise the product’s active default price row.
• Webhooks: findCatalogRowByStripePriceId looks up prices.external_id (including retired prices and retired parent products with paranoid: false) so Stripe price_* ids on grandfathered subscriptions still map to catalog rows.

• Catalog listings (publicProducts, billingDetails.availableProducts, non-SA products) exclude retired SKUs by default Sequelize paranoid behavior.
• Live subscriptions on a retired product still hydrate via includes/lookups with paranoid: false (productCatalog.ts, getCurrentSubscription, billing/trial/downgrade loaders).
• Quantity changes on a subscription already on a retired product remain allowed.
• Upgrade / downgrade / checkout targets must be active (assertProductActiveForPlanChange). Orgs may leave a retired plan onto an active target.
• Super Admin may still list retired products with showRetired.

• The first price created for a product is auto-defaulted.
• At most one active default per product (is_default = true AND retired_at IS NULL; partial unique index).
• Retiring or unsetting the last active default is blocked — promote another price to default first, then retire the old row.

• Usage plans: the default prices row is the flat base Stripe price; prices.metadata.externalUsageId holds a second metered Stripe price id (not the default row). getUsageSubscriptionPriceIds returns base + metered when present.
• Stripe line-item matching: webhooks and adapter code compare SubscriptionItem.price.id (via resolveStripeSubscriptionItemExternalId) to Stripe price ids from the resolution layer, then map back to catalog rows with findCatalogRowByStripePriceId.
• Another processor: the same columns hold that provider’s canonical ids; only adapter implementations are Stripe-specific.

​

Key architectural decisions

​

Decoupling from product logic

• Plans are Product rows (ProductType.Recurring or ProductType.OneOff) with thin metadata ({ model: seat_based | usage_based } for recurring, {} for one-off) in apps/backend/src/tools/rds/sequelize/models/product.ts. Commercial terms live on associated Price rows.
• Application features gate on AllScopes via canAccessScopes, which resolves scopes from the current org subscription’s product_id — not from Stripe objects at request time.
• Stripe is confined to apps/backend/src/tools/paymentProcessor/ (and webhook handlers that call tools.paymentProcessor).

​

Technologies and libraries

• Stripe Node SDK — API version from config (StripePaymentProcessorType, buildStripePaymentProcessor).
• PostgreSQL + Sequelize — subscriptions, products, prices, checkout_sessions, downgrade_requests, processed_webhooks_events, payment_methods, etc.
• Redis — webhook processing lock marker (webhooks_events helper), invoice preview cache, RBAC scope cache (apps/backend/src/tools/cache/webhooksEvents.ts).
• Queue abstraction (tools.queue) — QueueName.STRIPE_WEBHOOK for webhook payloads; BullMQ by default, swappable via config.
• GraphQL (Apollo) — billing queries/mutations under apps/backend/src/gql/.
• Zod — webhook payload validation (webhookValidators.ts).

​

2. Architecture

​

Layering

​

Interaction with the “functional core”

• Pure or deterministic helpers live under apps/backend/src/utilities/ (e.g. getQuantityBased, isFreeToPaidUpgrade, hasWebhookEventBeenProcessed).
• Side effects are isolated at boundaries: GraphQL resolvers, webhook consumer, and paymentProcessor implementations.
• Payment processor methods are async I/O; the StripePaymentProcessorType interface documents the contract (apps/backend/src/tools/paymentProcessor/stripe/types.ts).

​

Payment processor adapter

• Factory: buildPaymentProcessor switches on PaymentProcessorClientType:

export enum PaymentProcessorClientType {
  STRIPE = "stripe",
  STRIPE_MOCK = "stripeMock",
}

• Runtime type: PaymentProcessorType = Awaited<ReturnType<typeof buildPaymentProcessor>> — the concrete shape is the Stripe implementation (or STRIPE_MOCK in tests) returned from the factory.
• Injection: ToolsType includes paymentProcessor: PaymentProcessorType.

​

3. Plans and entitlements

​

How plans are defined

• type: ProductType.Recurring or ProductType.OneOff.
• metadata: thin packaging discriminator only:
  • Recurring seat-based: { model: RecurringModel.SeatBased }
  • Recurring usage-based: { model: RecurringModel.UsageBased }
  • One-off: {}
• external_id: Stripe Product id (prod_*).
• is_default: marks the free / default plan used when creating a default subscription (createDefaultSubscription loads where: { is_default: true }). The base free plan must also have a zero default price (isBaseFreeDefaultPlan / productCatalog.ts).

• external_id: Stripe Price id (price_*) — the billable subscription line.
• unit_amount, currency, billing_period, quantity_based: canonical commercial terms.
• metadata: seat resourceName; usage resourceName, eventName, externalUsageId (metered Stripe price id), pricingBands (see priceMetadata.ts).
• is_default: which price row new checkouts use when checkout_sessions.price_id is null.

​

How entitlements attach to plans

• Migration for tables: 20250428180842-addScopesAndRoles.ts.
• getRoleScopesFromProductIdAndRole loads scopes for a public role; non-public roles receive all scopes (rbac.ts).

​

Runtime entitlement checks

1. Resolver uses hasScopes middleware (hasScopes.ts).
2. canAccessScopes → getScopesForOrganizationMembership:
   • Resolves active subscription with getActiveSubscriptionByOrganizationId (ACTIVE_STATUSES: active, trialing, delinquent).
   • Loads product_id from that subscription.
   • Reads scopes from ProductRoleScope (+ Scope) or cache.

• confirmPayment requires one of BILLING_UPGRADE_SUBSCRIPTIONS, BILLING_DOWNGRADE_SUBSCRIPTIONS, BILLING_UPDATE_DETAILS, BILLING_CREATE_DETAILS (ScopeMatchMode.ANY).
• cancelDowngrade and confirmDowngrade require BILLING_DOWNGRADE_SUBSCRIPTIONS (ScopeMatchMode.EVERY, with isLoggedIn and populateUserWithMemberships on confirmDowngrade).
• cancelOrganizationTrial: Omit organizationId to cancel the trial for the current membership organization (portal and org admins). hasScopes enforces BILLING_DOWNGRADE_SUBSCRIPTIONS for everyone except super admins (super admins bypass that check). Non-super-admins must not pass organizationId (403 if they do). Super admins may pass organizationId to target a different organization.

​

Define a new plan (code / ops)

1. Create Stripe Product + Price(s); insert products with external_id = prod_* and thin product metadata ({ model: 'seat_based' } / { model: 'usage_based' } / {}).
2. Insert a default prices row with external_id = price_*, amount/currency/interval, and any usage metadata.
3. RBAC: insert rows into products_roles_scopes linking product_id, role (PublicRoles), and scope_id.
4. Cache: saving/destroying ProductRoleScope enqueues SCOPE_CACHE_RESET — no manual Redis flush required for normal CRUD.

// Product metadata (packaging only)
{ "model": "seat_based" }

// Default price row (commercial terms)
{
  "external_id": "price_…",
  "unit_amount": 2900,
  "currency": "USD",
  "billing_period": "month",
  "quantity_based": "manual",
  "metadata": { "resourceName": "seat" }
}

​

Add a new entitlement to an existing plan

1. Ensure a scopes row exists (unique name).
2. Insert products_roles_scopes (product_id, role, scope_id).
3. The ProductRoleScope.afterSave / afterDestroy hooks send SCOPE_CACHE_RESET so clearCachedScopes runs.

​

Product limits (numeric caps)

​

Bypass, limited, and blocked (per role)

📖 See also: .cursor/rules/product-limits.mdc for ownership and anti-patterns.

​

4. One-off purchases

​

Recurring checkout vs one-off (same session, different Stripe path)

​

End-to-end flow (skim this diagram first)

​

5. Subscription lifecycle

// apps/backend/src/tools/rds/sequelize/models/subscription.ts
export enum SubscriptionStatus {
  Active = "active",
  Trialing = "trialing",
  Delinquent = "delinquent",
  Cancelled = "cancelled",
}

export const ACTIVE_STATUSES = [
  SubscriptionStatus.Active,
  SubscriptionStatus.Trialing,
  SubscriptionStatus.Delinquent,
];

​

New subscription (organization onboarding)

1. Organization creation flows call createDefaultSubscription (subscription.ts).
2. That loads Product with is_default: true, computes quantity via getQuantityBased, then paymentProcessor.createSubscription.

1. User selects plan; frontend sets Redux checkout state (checkoutSlice.ts).
2. invoicePreview with changes resolves quantity and calls setCheckoutSession (invoicePreview.ts).
3. createIntent with PaymentType.CheckoutValidation: for free-to-paid, handleFreeToPaidUpgrade in createIntent.ts creates a Stripe subscription (payment_behavior: 'default_incomplete', items from plan + optional usage price).
4. User completes payment; Stripe emits webhooks.
5. paymentIntentSucceeded (when metadata type is checkout-related and current product is default) validates invoice/subscription lines against resolved Stripe price ids, updates subscriptions (external_id, product_id, price_id, quantity, cycle dates), cancels previous external subscription id, closes checkout session (paymentIntentSucceeded.ts).

​

Upgrade (paid → paid)

1. invoicePreview with changes (requires BILLING_UPGRADE_SUBSCRIPTIONS) builds preview via previewInvoice and persists intent via setCheckoutSession (invoicePreview.ts).
2. createIntent uses handlePaidToPaidUpgrade: creates a small hold PaymentIntent (CHECKOUT_VALIDATION_AMOUNT_CENTS = 50) in constants/checkout.ts.
3. confirmPayment cancels any pending DowngradeRequest, then confirmPayment on the processor (confirmPayment.ts).
4. payment_intent.amount_capturable_updated: paymentIntentAmountCapturableUpdated:
   • If no subscription: createSubscription utility (local + Stripe).
   • If subscription exists: updateSubscription with old product quantity 0 and new product quantity from getQuantityBased, then updates subscriptions.product_id and quantity.

​

Downgrade

1. User selects target plan; confirmDowngrade GraphQL mutation runs (confirmDowngrade.ts).
2. Cancel + create: confirmDowngrade cancels any existing pending DowngradeRequest row for the subscription (via paymentProcessor.cancelDowngradeRequest), then calls paymentProcessor.createDowngradeRequest to create/update the Stripe subscription schedule and write a downgrade_requests row (status = pending).
   • Schedule phase 1 mirrors live Stripe items; phase 2 replaces the full item set with the target product’s price ids from getUsageSubscriptionPriceIds (seat/base + any metered lines). It must not preserve leftover non-seat lines from the prior plan (e.g. usage → seat).
3. Completion: customerSubscriptionUpdated runs handleOpenDowngradeRequests. It completes the row when Stripe’s items match the target plan’s resolved Stripe price id (getStripePriceIdForProduct) and:
   • for product-changed downgrades, it hydrates subscription.product_id, subscription.price_id, and subscription.quantity from Stripe
   • for quantity-only downgrades, it completes when stripeQuantity === downgradeRequest.changed_to_quantity (customerSubscriptionUpdated.ts).
4. Cancel scheduled downgrade: cancelDowngrade + cancelDowngradeRequest.

​

Manual seat quantity sync with a pending product downgrade

1. Trigger: updateManualQuantity finds a pending product downgrade row (downgraded_to_product_id != currentProduct.id).
2. Current plan update (IMMEDIATE): it resolves the effective current seats with getQuantityBased(currentProduct, ...), then updates Stripe subscription quantity via paymentProcessor.updateSubscription and persists subscription.quantity.
3. Target plan sync: it calls syncPendingProductDowngradeScheduledQuantity, which resolves the effective target seats via getQuantityBased(downgradeRequest.downgradedToProduct, ...) before any Stripe/DB writes.
4. Stripe + DB coupling: the sync helper rebuilds phases and updates the existing schedule in place via stripe.subscriptionSchedules.update(downgradeRequest.external_id, { phases }), then persists downgradeRequest.changed_to_quantity = resolvedSeatQuantity.
5. Reconciliation (webhook): customerSubscriptionUpdated uses downgradeRequest.changed_to_quantity as scheduledQuantity for quantity-only completion and hydrates subscription fields from Stripe for product-changed downgrades (customerSubscriptionUpdated.ts).

⚠️ Watch out: DowngradeRequest.changed_to_quantity is the resolved seat count for downgradedToProduct. It must not be written from the raw UI quantity. The sync helper must call getQuantityBased before writing Stripe phase 2 or changed_to_quantity. (syncPendingProductDowngradeScheduledQuantity.ts)

⚠️ Watch out: updateManualQuantity selects the pending downgrade row inside a DB transaction using transaction.LOCK.UPDATE. The second call waits for the row lock, and the last committed mutation determines the final schedule rebuild. (updateManualQuantity.ts)

​

Cancellation

• No dedicated GraphQL “cancel subscription” mutation was found in apps/backend/src/gql (search for cancelSubscription only hits the payment processor and webhooks).
• When Stripe sends customer.subscription.deleted, customerSubscriptionDeleted:
  • Sets subscription status to cancelled.
  • Calls createDefaultSubscription to attach the org back to the default product (if that succeeds).

​

Renewal

• Not implemented as a separate batch job. Renewals are implicit Stripe billing cycles.
• customerSubscriptionUpdated updates cycle_start_date / cycle_end_date when period bounds change (shouldHydrateSubscriptionCycleDates).

​

6. Webhook handling

​

Events handled

​

Payment method ownership

​

Invoice document ownership

• invoice.created creates initial invoice rows (including open).
• invoice.updated updates lifecycle state changes (including void).
• invoice.paid / invoice.payment_succeeded / invoice_payment.paid stay enabled for checkout finalization flows and as compatibility ingestion paths.

​

Receive and verify

1. HTTP: createStripeWebhookHandler on POST /api/stripe/webhook, registered in index.ts before express.json() with express.raw so req.body is the raw buffer:
   • Stripe.webhooks.constructEvent with that buffer, stripe-signature, and the signing secret from typed config: getWebhookSigningSecret reads tools.configuration.tools.paymentProcessor.webhookSigningSecret (for Stripe, sourced from env such as STRIPE_WEBHOOK_SECRET in apps/backend/src/configuration/development.ts).
   • Drops events not in HandledStripeWebhookEvent with 200 (acknowledged but not queued).
   • hasWebhookEventBeenProcessed early exit → 200.
   • validateWebhookPayload → on failure 400 (body: Webhook Error: Invalid payload structure: ...).
   • On success, tools.queue.sendToQueue QueueName.STRIPE_WEBHOOK, payload JSON.stringify(event), respond 200.

​

Idempotency in the consumer

1. Open DB transaction.
2. hasWebhookEventBeenProcessed (cache + processed_webhooks_events).
3. cache.helpers.webhooksEvents.set with nx: true — if key exists, rollback and return (another worker owns the in-flight work).
4. validateWebhookPayload; on failure delete cache key, rollback.
5. Run handler; if handler returns false, delete cache key, rollback (event not recorded — Stripe may retry).
6. ProcessedWebhooksEvent.create { event_id, event_type }, commit.

​

Same webhook twice

• HTTP: second call sees DB (or cache) processed → 200 without re-enqueueing.
• Queue: second delivery sees processed or fails NX → no double insert of business effects.
• Handler returns false: row is not written to processed_webhooks_events; cache key removed — safe retry on Stripe’s part.

​

Add a new webhook handler

1. Add enum value to HandledStripeWebhookEvent (stripe.ts).
2. Add Zod validation branch in webhookValidators.ts and payload type in webhookTypes.ts.
3. Implement handler (payload, eventId, transaction, tools) => Promise<boolean>.
4. Register in getHandler in index.ts.
5. Extend HTTP router check (Object.values(HandledStripeWebhookEvent)) automatically if enum updated.
6. Add tests under __tests__/.

​

7. Idempotency

​

Implementation

​

Why it matters

• Stripe retries webhooks; SQS at-least-once delivery may duplicate.
• Without idempotency: duplicate subscription rows, double plan moves, or inconsistent downgrade_requests.

​

Retries

• Safe: Handler returns false → no ProcessedWebhooksEvent row; Stripe retry re-processes.
• Unsafe to assume: Returning true without idempotent business logic — always pair success with durable idempotency keys (DB unique + cache NX pattern used here).

​

Code reference

// apps/backend/src/utilities/billing.ts (abridged)
export const hasWebhookEventBeenProcessed = async (
  params: { eventId: string; transaction?: Transaction },
  tools: ToolsType,
) => {
  const isProcessedInCache = await webhooksEvents.get({ resource: eventId });
  if (isProcessedInCache) return true;
  const isProcessedInDatabase = await rds.models.ProcessedWebhooksEvent.findOne(
    {
      where: { event_id: eventId },
      transaction,
    },
  );
  return Boolean(isProcessedInDatabase);
};

​

8. Billing migrations (operational)

• Product lifecycle on Stripe + DB: createProduct, updateProduct, retireProduct, restaureProduct on StripePaymentProcessorType.
• Per-org upgrades via checkout + webhooks (subscription lifecycle, section 5).
• Downgrade scheduling via createDowngradeRequest.

​

Practical guidance (grounded in code behavior)

1. New plan for new customers only
   Use createProduct (products + default prices row). Leave existing subscriptions on their current product_id / pinned price_id.
2. Deprecate a plan
   Use retireProduct (processor) and hide the plan via the products query (see apps/backend/src/gql/queries/products.ts for out-of-stock/in-stock filtering). billingDetails loads products with Sequelize paranoid defaults (availableProducts = await rds.models.Product.findAll()), so retired SKUs are already excluded there; out-of-stock filtering for the admin catalog still lives on the products query. Not yet implemented: automatic migration of existing Stripe subscriptions to a replacement price without going through checkout/downgrade flows.
3. Change pricing without breaking existing subscriptions
   Create a new prices row (new Stripe Price), promote it to default, retire the old price row. Existing subscriptions keep billing on the old rate via pinned subscriptions.price_id. Do not change products.external_id (prod_*) for live plans.
4. Grandfathering
   Handled by Stripe subscription item price id + DB subscriptions.price_id (pinned internal prices.id, including retired price rows).

​

9. Payment processor adapter

​

Interface definition

​

Stripe implementation

• Entry: buildStripePaymentProcessor constructs a real Stripe client from secretKey / apiVersion (or injected config.stripe for tests).
• Settings: e.g. quantityDowngradePolicy passed into downgrade/sync helpers.

​

Swapping Stripe for another provider

1. New PaymentProcessorClientType value + Zod branch in validate.ts.
2. New module implementing the same method surface expected by resolvers/webhooks (or refactor to a narrower shared interface — today the codebase assumes Stripe-shaped flows).

​

stripeMock (STRIPE_MOCK)

• Config: PaymentProcessorClientType.STRIPE_MOCK — only { client: 'stripeMock' } per schema (validate.ts).
• Implementation: createTestStripePaymentProcessor returns stubbed methods (createIntent → failure, retrieveInvoice / cancelSubscription reject unless tests stub them, etc.).

​

10. Free plan and upgrade triggers

​

Free plan

• Identified by Product.is_default === true and default price unit_amount === 0 (isBaseFreeDefaultPlan, used by isFreeToPaidUpgrade).
• createDefaultSubscription always binds new orgs to is_default: true product.

​

Upgrade prompts (frontend)

• Checkout state: checkoutSlice.ts — setProduct resolves quantity using getQuantityBased from apps/portal/src/utils/memberships.ts (mirror of server rules).
• Server-side preview: invoicePreview enforces BILLING_UPGRADE_SUBSCRIPTIONS when form.changes is present (invoicePreview.ts).

​

Customize triggers

• UI: Gating is standard React routing + feature checks; search frontend for billing routes and scope checks (generated ScopeEnum in hooks.ts aligns with AllScopes names).
• API: Add or restrict AllScopes on roles via products_roles_scopes for each plan.

​

11. Extending the billing system

​

New billing provider

​

Usage-based / metered billing

• Product packaging: ProductType.Recurring with metadata.model === RecurringModel.UsageBased (product.ts).
• Price commercial terms: default prices row holds flat base amount; prices.metadata holds eventName, externalUsageId, pricingBands, resourceName (priceMetadata.ts).
• Reporting usage: call paymentProcessor.recordUsage — uses stripe.billing.meterEvents.create and increments SubscriptionUsageCycle when cycle dates exist (recordUsage.ts).
• Checkout / subscription items: createIntent appends meter price items from getUsageSubscriptionPriceIds when the product is usage-based.

​

New plan tier

1. createProduct via Super Admin or processor API (Stripe Product + Price, products + prices rows).
2. Seed products_roles_scopes for each PublicRoles value that should differ per tier.
3. Expose in admin / super-admin GraphQL if using built-in product management mutations.

​

Customize checkout flow

• Backend: TTL and amounts in apps/backend/src/constants/checkout.ts (CHECKOUT_SESSION_TTL_MINUTES, CHECKOUT_VALIDATION_AMOUNT_CENTS).
• Processor: setCheckoutSession / getCheckoutSession — see Stripe implementations under apps/backend/src/tools/paymentProcessor/stripe/.
• Frontend: Redux checkout slice + billing pages under apps/portal/src (grep createIntent, confirmPayment, invoicePreview).

​

12. Common pitfalls

​

Testing without real charges

• Use Stripe test mode keys in config (development.ts pattern).
• Use PaymentProcessorClientType.STRIPE_MOCK for tests that stub the processor, or buildStripePaymentProcessorWithMock in processor tests (apps/backend/src/tools/paymentProcessor/__tests__/stripe/_buildProcessorWithMockStripe.ts).
• Backend tests run via make test module=backend (Docker) per project rules.

​

Known edge cases

• Multiple pending downgrade requests: DB migration downgrade_requests_one_pending_per_subscription (partial unique on subscription_id where status = 'pending') enforces at most one pending row per subscription in 20250608010922-addDowngradeMarking.ts.
• Handler false vs thrown error: false triggers rollback + cache delete + Stripe retry; thrown error in consumer deletes cache key and rethrows — understand your active queue adapter’s retry and DLQ configuration (BullMQ retry settings by default; SQS visibility timeout if using SQS).
• Currency change on an active subscription: not supported in-product. Prefer cancel → re-subscribe on the target currency (Single currency).

​

Related files (quick index)

​

What’s next?

📖 See also: RBAC for how hasScopes resolves permissions from product-role mappings and Redis cache. For phased trial overlap and post‑trial fallback, the rule lives in apps/backend/src/utilities/trials.ts (see Pending downgrade overlap vs nominal post‑trial fallback above).