Architecture boundary

Vibes and Pulses

This is the core architecture split for Vibecodr: editable source lives in the capsule, published Vibes handle interactive client runtime on VXBE hosts, and Pulses own trusted backend operations on same-origin /api routes.

Authoritative client-versus-edge execution model for Vibecodr.

Implementation focus

Use this boundary first. It prevents accidental secret exposure and keeps user-facing surfaces fast and remixable.

Expected outcomes

Decide correctly between client runtime and server-side execution.
Understand where capsules end, artifacts begin, and why public playback uses artifact-scoped launch contracts.
Avoid coupling public UI behavior to trusted credentials.
Scale safely by moving only trust-requiring logic into Pulses.

Client and trusted execution

Vibes run in the browser as sandboxed client experiences. Pulses run as trusted backend endpoints on the platform-managed edge. The distinction protects creators and viewers by keeping credentials and privileged operations away from client-visible code.

A Combo is a project that uses both sides: the vibe owns interactive UI while Pulses own backend work such as secrets, schedules, webhooks, storage, or third-party APIs.

Use vibes for UI, graphics, interaction, and public browser behavior.
Use Pulses for secrets, OAuth/token work, provider calls, schedules, and durable side effects.
Do not put private API keys, platform grants, or owner-only operational metadata in browser code.

Same-origin backend shape

Pulse endpoints are called through same-origin /api routes so the browser app can talk to backend behavior without hardcoding a separate service host. That does not make the endpoint private by itself.

If endpoint behavior should be restricted, implement request validation and authorization in the Pulse handler.

Public endpoint availability is separate from private source visibility.
The platform mediates secrets and grants; the application still owns its business rules.
Keep response bodies viewer-safe.

How Pulse State helps Pulses coordinate work

A Pulse is creator-authored backend code. Pulse State gives that code a small, platform-managed memory for operation keys, so repeated calls can agree on what is new, already running, completed, failed, or safe to retry.

runOnce() coordinates one named Pulse State resource plus one trusted key inside the Pulse owner/deployment scope. The key defines the operation being protected, so stable keys such as verified webhook event ids, scheduled window keys, or form idempotency tokens are the best fit.

Same Pulse, same state resource, same key: coordinated as the same operation.
Same Pulse, same state resource, different key: a new operation.
Different Pulse or different owner: a separate coordination scope.
Use Pulse State for operation lifecycle. Use a real data surface or connected service for application records that need querying, editing, or long-term storage.

Same key means same coordinated operation typescript

const event = await env.webhooks.verify("stripe", {
  secret: "STRIPE_WEBHOOK_SECRET",
});
const key = `stripe:event:${event.id}`;

return env.state.webhookDedupe.runOnce(key, async () => {
  await env.fetch("https://api.example.com/fulfill", {
    method: "POST",
    auth: env.secrets.bearer("PROVIDER_API_KEY"),
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ eventId: event.id }),
  });

  return { accepted: true };
});

Example and read next

Example: a vibe needs to call OpenAI, Stripe, or GitHub. Keep the interactive UI in the browser, put the credential-backed provider call in a Pulse, and have the vibe call a same-origin /api route.

Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system.

Read next: /blueprints (/blueprints)
Read next: Pulse SDK & Handlers (/docs/handlers)
Read next: Secrets & APIs (/docs/secrets)
Read next: Calling Pulses (/docs/calling-pulses)