Build on the web.
Not around it.

The web already has
an application protocol.
We should use it.

The default architecture for modern web apps is JSON APIs consumed by a JavaScript framework. It works — but it reinvents, in application code, what the web platform already provides natively.

Hypermedia-driven architecture delivers the same capabilities — typed responses, declarative auth, server-side composition, event-driven invalidation, cursor-based pagination — by making HTML the primary wire format and using HTTP as it was designed.

Instead of building a codegen pipeline, a typed client library, custom framework hooks, and an API seam to mediate between them, you ship HTML fragments from the edge and let the browser's native hypermedia engine do the rest.

What you're actually
paying for.

When a team chooses a JSON-first architecture with a heavy client framework, here's what they're actually building and maintaining — often without realising the accumulated cost.

HTML over the wire.
Compute at the edge.

The server is not a JSON vending machine. It's a hypermedia engine that responds to HTTP requests with HTML fragments the browser can render directly — or JSON when a non-HTML consumer (mobile app, CLI, third-party) needs it.

How a request flows

The tools, not the rules.

Each piece is chosen because it's the right tool for a hypermedia architecture on Cloudflare's edge platform. No polyfills, no workarounds, no "we'll migrate later."

Three operations.
That's all you need.

Every web application boils down to three things: reading data, writing data, and receiving live updates. In a hypermedia architecture, these map directly to HTTP verbs and SSE.

// Dashboard panel — one GET, one HTML response
<div
  hx-get="/api/dashboard/metrics"
  hx-trigger="load, metrics.updated from /sse/dashboard"
  hx-swap="innerHTML"
>
  Loading metrics...
</div>

// Update settings — form POST, returns updated panel
<form
  hx-post="/api/settings"
  hx-headers='{"idempotency-key": "{{uuid}}"}'
  hx-target="#settings-panel"
  hx-swap="innerHTML"
>
  <input name="key" type="text"/>
  <textarea name="value"></textarea>
  <button>Save</button>
</form>

// Live feed — SSE pushes fragment updates
<div
  data-on-load="$$sse('/api/feed/live')"
  sse-swap="feed-update"
>
  <div id="items">
    <!-- Server pushes updated items as HTML -->
  </div>
</div>

Durable Objects + SSE.
The right tool for each job.

Most teams build a subscription system from scratch — channels, cursors, replay, backpressure, auth re-check on reconnect. Cloudflare's platform gives you most of this for free.

Typical subscription channels

Typed, composable service layer.

Effect TS is the backbone of the server-side logic. It doesn't replace Hono or Drizzle — it composes them. Every handler, every database query, every side effect runs inside an Effect pipeline that provides typed errors, structured concurrency, dependency injection, and observability for free.

class NotFoundError {
  readonly _tag = "NotFoundError";
  constructor(readonly entity: string, readonly id: string) {}
}

class RateLimitedError {
  readonly _tag = "RateLimitedError";
  constructor(readonly retryAfter: number) {}
}

// Exhaustive matching — compiler catches missing cases
const renderError = Effect.catchTags({
  NotFoundError: (e) => renderNotFound(e.entity, e.id),
  RateLimitedError: (e) => renderRateLimited(e.retryAfter),
  ValidationError: (e) => renderValidation(e.fields),
  ...// missing a tag? Compile error.
});

// Service declaration
class UserService extends Effect.Service<"UserService">()({
  getProfile: Effect.fn((id: string) =>
    Effect.gen(function* () {
      const db = yield* Database;
      const cache = yield* CacheService;
      const user = yield* cache
        .getOrFetch(`user:${id}`, () =>
          db.query.users.findById(id)
        );
      if (!user)
        yield* Effect.fail(new NotFoundError("user", id));
      return user;
    })
  ),
}) {}

// Handler uses it — no imports, no wiring
const handler = Effect.gen(function* () {
  const svc = yield* UserService;
  const profile = yield* svc.getProfile(id);
  return renderProfile(profile);
});

// Retry transient DB failures, not validation errors
const safeQuery = db.query.users
  .findById(id)
  .pipe(
    Effect.retry(
      Schedule.exponential("100 millis")
        .pipe(Schedule.jittered)
        .pipe(Schedule.whileOutput(_ => _ < "5 seconds"))
    ),
    Effect.catchTag("DatabaseError", () =>
      Effect.fail(new DegradedError("user_data"))
    )
  );

// Every handler auto-instruments
app.get("/api/dashboard/metrics",
  authenticate(),
  authorize('admin', 'viewer'),
  async (c) => {
    const program = Effect.gen(function* () {
      const svc = yield* MetricsService;
      const data = yield* svc.getDashboard(c.req.param('id'));
      return c.html(<MetricsPanel {...data} />);
    }).pipe(
      Effect.withSpan("metrics.getDashboard", {
        attributes: { operation: "metrics.getDashboard" }
      }),
      renderError
    );
    return runHandler(program);
  }
);

Meaningful responses,
not error codes.

In a JSON architecture, errors are typed objects the client maps to UI components. In a hypermedia architecture, the server renders the response directly — so errors become HTML fragments that mean something to the user.

// Validation middleware — collects, doesn't reject
app.post("/api/items",
  softValidate(CreateItemSchema),
  async (c) => {
    const { issues, data } = c.get('validation');

    if (issues.length > 0) {
      // Return HTML with inline errors — same form, error messages rendered
      return c.html(
        <ItemForm data={data} errors={issues} />,
        { status: 422 }
      );
    }

    // Happy path — create item, return updated list
    const item = await createItem(data);
    return c.html(<ItemList items={items} />);
  }
);

// Effect error → HTML fragment mapping
const renderError = Effect.catchTags({
  NotFoundError: (e) =>
    html(<EmptyState
      title={`No ${e.entity} found`}
      hint="This may have been removed or the link is incorrect."
    />),

  ValidationError: (e) =>
    html(<FormErrors fields={e.fields} />),

  RateLimitedError: (e) =>
    html(<RateLimitBanner retryAfter={e.retryAfter} />),

  DegradedError: (e) =>
    html(<PartialDataWarning source={e.source} />),

  ForbiddenError: (e) =>
    html(<NoPermission required={e.requiredRole} />),
});

Same requirements.
Less complexity.

How each architecture addresses the same operational requirements.

Show, don't tell.

The same feature — a dashboard panel with live metrics and settings. How it's built in each architecture.

JSON-first: ~40 lines across 4 files

// 1. Schema (packages/api-contracts/operations/dashboard.ts)
export const dashboardGetMetrics = {
  input: z.object({ dashboardId: z.string() }),
  output: z.object({ metrics: MetricsSummary, settings: Settings, ... }),
  policy: { roles: ['admin', 'viewer'] },
  cache: 'private',
};

// 2. Codegen'd hook (auto-generated)
export function useDashboardGetMetrics(input) { ... }

// 3. Feature component
function MetricsPanel() {
  const { data, error } = useDashboardGetMetrics({ dashboardId });
  if (error) return <ErrorBoundary error={error} />;
  return <Panel metrics={data.metrics} settings={data.settings} ... />;
}

// 4. API endpoint (seam)
export async function POST(req) {
  const actor = await resolveActor(req);
  const input = schema.parse(await req.json());
  enforcePolicy(actor, schema.policy);
  return backend.dashboard.getMetrics(input, actor);
}

Hypermedia: ~20 lines across 2 files

// 1. HTML (the "component")
<div
  hx-get="/api/dashboard/metrics"
  hx-trigger="load, metrics.updated from /sse/dashboard"
  hx-swap="innerHTML"
>
  Loading metrics...
</div>

// 2. Hono route handler (the "backend")
app.get("/api/dashboard/metrics",
  authenticate(),
  authorize('admin', 'viewer'),
  async (c) => {
    const program = Effect.gen(function* () {
      const svc = yield* MetricsService;
      const data = yield* svc.getDashboard(c.req.param('id'));
      return c.html(<MetricsPanel {...data} />);
    }).pipe(
      Effect.withSpan("dashboard.getMetrics"),
      renderError
    );
    return runHandler(program);
  }
);

Not theory. Production experience.

This architecture isn't assembled from blog posts. Every piece of it comes from shipping real systems and learning where the default approach breaks down.

Honest about the trade-offs.

No architecture is perfect. Here are the genuine considerations.