Vibecodr - Platform Overview

Vibecodr is a social timeline of playable vibes: small interactive experiences you can run inline, tune with params, remix, and share. This page summarizes the current runtime, storage, embed, dependency, and automation architecture based on the codebase.

1. What Vibecodr Does

Vibecodr lets people publish and share runnable vibes across the feed, player, profiles, embeds, and vanity URLs. Vibes run in the browser; pulses handle privileged server-side work when needed.

The core stack is organized into:

2. Vibes

A vibe is the runnable experience attached to a post. It appears in these surfaces:

Vibes run purely client-side in sandboxed iframes. They do not have access to D1, R2, KV, Durable Objects, or platform secrets. External network calls are from the browser and are restricted by the runtime CSP; privileged work must go through pulses.

Runtime budgets are enforced per surface and plan:

3. Project Types

Vibecodr uses file-based project type detection to classify projects based on structure.

Three Project Types

Pulse files are detected from either server/weather.ts or src/server/weather.ts. Both map to /api/weather. Pulse and Combo projects consume one deployment slot.

4. Pulses

A pulse is a server-side function running on Workers for Platforms. Pulses are the only way to run trusted backend logic with secrets, OAuth connections, or D1. 

import { definePulse } from "@vibecodr/pulse";

export default definePulse(async (input, env) => {
  // env includes: kv, fetch, log, secrets, connections, event, request, waitUntil, db? (Pro only)
  return { ok: true };
});

Note: env.ai and env.email are not available. Use env.secrets.fetch() or env.connections.fetch() for external APIs. Egress is enforced by the Outbound Worker and dispatch proxies (infra blocklist + redirect re-validation).

5. How Vibes Use Pulses

  1. Vibe asks the host to run a pulse via postMessage
  2. Player calls POST /pulses/:id/run and receives a grant
  3. Dispatch validates the grant, enforces quotas, and invokes the pulse worker
  4. Response is returned to the player and delivered back to the vibe

6. Automations, Webhooks, and Triggers

Automations are defined as triggers that dispatch pulses. Trigger kinds: runtime_event, http_webhook, cron, and manual.

Webhook signatures are supported with shared, GitHub, or Stripe semantics using headers like x-vibecodr-signature, x-signature-sha256, x-hub-signature-256, and stripe-signature.

7. Dependency Pipeline and Import Maps

Publishing compiles a capsule into an immutable artifact plus a runtime manifest with a deterministic import map.

8. Storage and Quotas

Storage uses R2 with a D1 index (r2_objects) for quotas, browsing, and cleanup. Paid plans get dedicated buckets with shared-bucket fallback for reads; Free uses the shared bucket.

9. Plans and Usage Semantics

Plan limits are enforced by shared constants in PLAN_LIMITS.

Note: Pulse run quotas count server invocations, not vibe plays.

10. Recipes (Deprecated)

The recipes system (saved parameter presets) is deprecated and recipe API routes have been removed.

11. Remix Lineage

Remixes create parent-child relationships between capsules. Lineage can be queried via GET /capsules/:id/remixes.

12. Messaging

13. Search

14. Live Streaming (Deferred)

Live streaming is not enabled in the current codebase.

15. Social Features

Social features include follows, likes, comments, saves, blocks, and mute lists.

16. Terminology Reference