Customize the Starter

VibeAny is a starter, not a finished product. Replace its example catalog and copy, but preserve the provider-neutral boundaries around checkout, credits, storage, and model routing.

Customize the product catalog

The catalog source of truth is src/lib/config/products.ts. It defines:

• subscription plans and monthly credit grants;
• credit packs and their fulfillment amounts;
• example one-time products;
• Stripe Price IDs and Creem Product IDs from environment variables;
• the CREDITS_PER_IMAGE cost used by image generation.

Display text is localized separately under src/i18n/locales/*. When changing a public product, update the catalog, translations, pricing UI, provider dashboard objects, environment variables, and tests as one change.

Add or remove a subscription plan

1. Add or remove the plan in PLANS.
2. Define each billing interval you actually display.
3. Add provider ID mappings for Stripe and Creem, or only for the provider your deployment supports.
4. Update provider readiness rules if the visible built-in SKU set changes.
5. Update pricing and billing translations.
6. Verify checkout, webhook plan resolution, the monthly credit grant, cancellation, and portal behavior.

An environment variable alone does not create a working plan. For example, Enterprise variable names exist as extension points, but Enterprise is not in the built-in PLANS array.

Add a one-time product

Credit packages have built-in fulfillment. They use credits_<package-id> SKU keys and add an idempotent credit lot after a completed checkout webhook.

The included landing products demonstrate entitlement configuration, but the current checkout catalog rejects non-credit one-time products until their fulfillment path is implemented. Before exposing one:

1. define its provider identifiers;
2. implement a durable, idempotent entitlement or custom fulfillment adapter;
3. extend the checkout catalog to allow that fulfillment type;
4. persist an auditable purchase mapping if the product needs refunds or revocation;
5. add webhook replay tests.

Do not treat the unused example orders table as proof that orders are recorded automatically.

Feature flags are operational gates

Keep optional capabilities disabled until their dependencies are ready:

NEXT_PUBLIC_ENABLE_PAYMENTS=false
NEXT_PUBLIC_ENABLE_IMAGE_GENERATION=false

Enabling payments also requires PAYMENTS_PROVIDER, the selected provider's credentials and webhook secret, every visible catalog identifier, and CRON_SECRET when subscriptions are present.

Enabling image generation requires at least one configured model provider. Durable generated-image URLs additionally require object storage, although generation can return the model provider's original URL when storage is unavailable.

Run npm run preflight after every environment or feature-flag change.

Preserve architecture boundaries

The main dependency direction is:

HTTP/UI adapters
  -> application use cases and ports
    -> infrastructure adapters
      -> provider SDKs and persistence

Practical rules:

• keep App Router route handlers thin;
• keep provider SDK imports and secret reads in infrastructure;
• put authorization and orchestration in application use cases;
• put pure credit and subscription rules in domain code;
• expose stable feature APIs to UI components;
• never branch on Stripe or Creem in unrelated UI or business modules.

Add another payment provider

Stripe and Creem share a contract, so a future provider such as Paddle should be added as an adapter rather than a second payment stack:

1. extend the payment provider name union;
2. implement checkout, scheduled cancellation, and optional portal behavior behind the gateway port;
3. implement raw signature verification and event normalization separately;
4. map provider product identifiers through the catalog;
5. register the gateway and webhook verifier in infrastructure composition;
6. add configuration readiness and environment validation;
7. add contract tests for metadata, idempotency, event ordering, portal, cancellation, and replay.

This extension does not change the current operating model: one deployment still selects one active provider for new checkout and webhook traffic.

Verification loop

npm run preflight
npm run architecture:check
npm run test:unit
npm run typecheck:all
npm run lint
npm run build

Use provider sandbox tests and database read-back whenever a change affects checkout, fulfillment, subscriptions, credits, or generated-asset persistence.

Continue with Storage and AI image generation or review the payments operating model.