Vibecodr – How It Works

1. Web App and API Boundary

The web UI is a React single-page app (apps/web) that uses React Router for client-side navigation. All data comes from an edge Worker API whose base URL is computed by helpers in the web app.

A typical browser request follows this path:

1. User navigates to a route like /, /player/:postId, or /settings
2. The SPA route component uses an API helper to call the Worker API (e.g., GET /posts, GET /profile/:handle)
3. The API Worker reads/writes from D1, R2, Durable Objects, and Analytics Engine
4. The route component maps the JSON response into view models and renders the page

Key idea: All data flows through a single API Worker endpoint. The SPA never talks directly to storage services.

2. Feed and Post Flow

The home feed and post views are backed by feed endpoints in the API worker:

• Home feed (/) – Calls feed APIs with mode parameter (latest, following, or foryou) and optional search/tag filters
• Discover (/discover) – Calls discovery variants for tag-focused vibes
• Post detail (/post/:id) – Fetches the post; app posts redirect to /player/:id

The SPA uses shared schemas from @vibecodr/shared to validate API responses before mapping them into feed and player models.

3. Feed Ranking and Personalization

Feed ranking uses linear, non-ML scoring over existing signals to keep behavior auditable while allowing future model swaps without API changes.

Signals Used

• Exponential recency decay
• Engagement rate (likes, comments, saves, runs, completions, remixes, shares)
• Creator/topic affinity
• Mild boosts for runnable vibes and author plan/featured flags

Feed Modes

• Following feed – Recency-weighted with creator and topic affinity inputs
• Discovery feed – Global trending using engagement velocity/acceleration, size penalty for large creators, boost for runnable vibes
• For You feed – Blends following, topic matches, discovery pool, and fresh posts; enforces diversity (no >3 consecutive posts per author)

Safety Filters

Excludes muted/blocked users, quarantined content; applies search/tag filters before scoring; falls back to discover feed if personalization is empty.

4. Vibe Runtime Execution

When a user opens a vibe in the player at /player/:postId, the system loads and runs that vibe in a sandboxed iframe:

1. Player page fetches the post and associated runtime manifest from the Worker API
2. Player enforces client-side runtime budgets (max concurrent runners, boot timeouts by surface and plan)
3. Runtime HTML and bundle are served from a separate origin and embedded in an iframe with sandbox attributes and restricted CSP
4. The iframe runs user code purely client-side; there is no server-side Node.js runtime
5. Iframe and host communicate via postMessage protocol carrying params, logs, and telemetry
6. Logs and runtime events are forwarded to the Worker; runs are finalized via runtime completion APIs

Key idea: Vibes execute entirely in the browser. The iframe is sandboxed and communicates with the host only via postMessage. No server-side Node.js runtime.

Runtime Budgets

• maxConcurrentRunners – Caps how many vibes can run at once
• clientStaticBootMs – How long a vibe has to signal ready before timeout
• webContainerBootHardKillMs – Hard deadline for heavier runtimes

5. Pulse Execution Flow

Pulses are per-user server-side functions deployed on Workers for Platforms. The execution path is implemented in the API Worker and dispatch worker.

1. Pulse is created and managed via pulse APIs in workers/api
2. Deployment scripts build and deploy a per-pulse Worker using the template in workers/vibe-template
3. Manual runs are quota-checked against the user's plan in the API Worker
4. Vibes and triggers use grant-based execution: API mints a short-lived grant, host calls pulse run endpoint with grant as bearer token
5. Dispatch worker validates grant, enforces rate limits and concurrency caps, checks kill switches
6. Dispatch routes to the user's pulse Worker in the dispatch namespace
7. Pulse Worker returns a Response or JSON result; dispatch attaches metadata headers

Key idea: Browser only talks to API Worker; pulses are always reached via grant-based dispatch worker. Grants are short-lived (30-90s) and scoped to {userId, pulseId}.

6. Integrations and Proxy Flow

Integrations and their secrets are modeled in D1 tables and surfaced through the API Worker.

1. Integration is created with type, name, and config; secrets are stored encrypted with AES-GCM
2. Vibes are associated with integrations so a vibe (and its pulses) knows which provider config to use
3. Server-side code sends external HTTP requests through a proxy that enforces per-provider host allowlists and blocks private/loopback IPs
4. Proxy derives auth headers from stored secrets and returns upstream response after stripping sensitive headers

Supported Providers

OpenAI, Supabase, Stripe, Slack, Discord, GitHub, email services, and generic HTTP endpoints through a single, observable gateway.

7. Safety, Limits, and Plans

Safety and cost controls are implemented across the API Worker, dispatch worker, and shared config:

• All write endpoints wrapped in auth checks; moderation/admin endpoints enforce role checks
• Public read endpoints are rate-limited via Cloudflare and in-Worker controls
• Expensive operations (imports, publishes, runs, pulse executions) checked against plan-specific quotas before work is performed
• Runtime iframes are cross-origin and sandboxed; network access goes through HTTPS/WSS allowances or integration proxy
• Plan limits defined once in packages/shared/src/plans.ts and consumed by both web app and API Worker

Plan Limits Summary

8. Real-time Streams

Vibecodr provides SSE streams for admin analytics:

• Admin Analytics (GET /admin/runtime-analytics/stream) – Pushes runtime event deltas and compile latency stats. Admin-only.

Notifications use client-side SWR polling (GET /notifications/unread-count) for cost efficiency. Streams send heartbeats to keep connections alive; clients back off on 429/5xx and retain REST endpoints as fallback.

9. Key API Endpoints

Anchor endpoints organized by domain:

10. Architecture Summary

Taken together, these flows describe how a request moves through Vibecodr: from the browser into Workers, through D1/R2/Durable Objects and back, using only the behavior defined in the codebase.

Key idea: Three-layer architecture. Browser SPA handles UI. API Worker handles data and orchestration. Dispatch Worker routes to isolated per-user pulse Workers. Each layer adds security/isolation.