---
title: "Architecture"
description: "The entire product (SSR app, API, generation pipelines, app sandbox, search, billing) runs in one Cloudflare Worker at the edge."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.murl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

murl is built as a **single Cloudflare Worker**: one deployable unit serving
the web app, the API, WebSockets, asset delivery, and the app platform. There
are no servers to scale and no regions to pick; the whole product runs at the
edge, globally, from one artifact.

## Request path

Every request enters one dispatcher and routes by prefix:

| Prefix | Handler |
|---|---|
| `/` | React Router 7 server-side rendering (the product UI) |
| `/api/*` | JSON API (auth-gated, module-per-feature controllers) |
| `/ws/*` | WebSocket upgrade into a Durable Object (live generation progress) |
| `/apps/{id}/*` | Dynamic Worker loader (creator apps in sealed sandboxes) |
| `/r2/*` | Media serving from object storage |

## Stateful pieces

Long-running work doesn't fit a request/response lifetime, so state lives in
**Durable Objects** and **Workflows**:

- **Generation executor** (DO): runs a page's block pipeline with per-step
  pricing, provider calls, progress events over WebSocket, and wallet
  settlement.
- **Studio job tracker** (DO): live job state for the editor.
- **App storage** (DO): per-`(app, user)` SQLite document collections behind
  the SDK's `storage()` API.
- **Authoring agent** (DO): the conversational agent that vibe-codes apps.
- **App chains** (Workflow): durable multi-step model runs started by apps;
  they survive the user closing the page and resume without double-charging.
- **Royalty settlement** (Workflow): the monthly creator-pool computation
  and payout run; idempotent, resumes safely.

## Data and media

- **Postgres (Neon)** through Cloudflare Hyperdrive edge pooling, with one
  driver, one schema, and hand-written SQL migrations.
- **R2 object storage** for all generated and uploaded media.
- **Vectorize** powers marketplace search: semantic vectors fused with
  Postgres keyword search, re-ranked, then hydrated so Postgres re-enforces
  every filter.
- **Cloudflare AI Gateway** fronts every model call: routing, provider
  failover, and observability in one place.

## The app sandbox

Creator apps are the part most platforms won't attempt: arbitrary
user-authored code served on the platform's own domain. murl runs each app as
an isolated worker via Cloudflare's Worker Loader with **no network egress and
no bindings except the injected SDK**; the [SDK](/sdk) is, by construction,
the complete capability surface of any app. Spending is impossible except
through one audited chokepoint, which is also where usage attribution for
[creator payouts](/economics) is recorded.

## Engineering posture

The repo ships with a single CI gate that runs design-token linting, a UI
component registry drift check, SDK documentation coverage, API collection
coverage, a full typecheck, and the production build. Every push to main
either passes all of it or doesn't deploy.

Source: https://docs.murl.ai/architecture/index.mdx