Deployment Modes

Guapocado has two server-side deployment modes.

Most teams should start with managed edge API mode. Local read-model mode is an optimization for teams that need local reads or local reporting.

Managed Edge API Mode

In managed edge API mode, your app calls Guapocado’s hosted API through the SDK.

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId,
});

await guap.has("advanced-analytics");

Use this mode when:

• you want the smallest integration
• network reads are acceptable
• you do not want Guapocado tables in your app database
• you want Stripe webhook projection handled outside your app

This is the default and recommended path.

Local Read-Model Mode

In local read-model mode, Guapocado forwards domain events to your app. Your app stores a local projection of customers, subscriptions, purchases, entitlements, usage, and invoices.

The SDK can then check local data first:

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId,
  adapter: createGuapDrizzleAdapter(db),
});

Use this mode when:

• entitlement checks are on a very hot path
• you need reads to work without a Guapocado API round trip
• you want SQL reporting over projected billing state
• you already operate webhook delivery and database migrations

Writes still go through Guapocado:

• usage consumption
• usage refunds
• usage settings
• limit expansion settings
• checkout
• subscription changes
• webhook registration

Local read model changes where reads come from. It does not make your app the payment system.

How to Decide

Start with managed edge API mode if you are unsure.

Move to local read-model mode only when you have a concrete reason:

• measurable latency problem
• availability requirement
• reporting requirement
• existing architecture that expects local projections

You can design your app so the switch is small. Keep billing checks behind your own small helpers:

export function createBilling(customerId: string) {
  return createGuapocadoClient({
    apiKey: process.env.GUAPOCADO_API_KEY!,
    customerId,
    // Add adapter later if you move to local read-model mode.
  });
}

Environment Targets

Both modes can run against sandbox or production. The API key selects the environment.

GUAPOCADO_API_KEY=sk_guap_test_...
GUAPOCADO_API_KEY=sk_guap_live_...

End-user apps should call:

https://api.guapocado.dev