# How OpenSEO Leverages Cloudflare Workers for Serverless Architecture

> Discover how OpenSEO uses Cloudflare Workers for a serverless architecture. Experience edge execution with TanStack Start R2 and Access for a zero-trust SEO platform.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: architecture
- Published: 2026-07-23

---

**OpenSEO runs its entire backend as a Cloudflare Worker, executing at the edge with TanStack Start routing, R2 caching, and Cloudflare Access authentication for a fully serverless, zero-trust SEO platform.**

OpenSEO is an open-source SEO platform built on a fully serverless architecture using Cloudflare Workers. The codebase in the `every-app/open-seo` repository eliminates traditional server management by running all backend logic at Cloudflare's edge locations. This architecture combines **TanStack Start** for server-side rendering, **R2 object storage** for caching, and **Cloudflare Access** for zero-trust security.

## Worker Entrypoint and Request Routing

The application exposes a single **Worker entrypoint** defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) that extends `Cloudflare.WorkerEntrypoint`. This file compiles into the executable script deployed to Cloudflare's edge network.

The entrypoint initializes a TanStack Start request handler that routes incoming HTTP requests to the appropriate server functions. Unlike traditional Node.js servers, this handler operates within Cloudflare's V8 isolates, providing instant cold starts and global distribution.

```typescript
// src/server.ts – Worker entrypoint (simplified)
import { createRequestHandler } from "@tanstack/start/server";
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // TanStack Start provides a request handler that works in a Worker
    const handler = createRequestHandler({ /* routes */ });
    return handler(request, env, ctx);
  },
} as ExportedHandler<Env>;

```

The TypeScript definitions in [`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts) declare the environment bindings, ensuring type safety when accessing KV namespaces, R2 buckets, and secrets within the Worker runtime.

## Deployment Configuration and Infrastructure as Code

OpenSEO uses **Wrangler** as its deployment toolchain, configured via `wrangler.jsonc`. This configuration file declaratively defines the Worker name, KV namespaces, R2 buckets, and secret bindings required for operation.

The repository includes a **Deploy to Cloudflare** button that provisions the entire stack via Wrangler. When triggered, it automatically creates the Worker, binds the `OPEN_SEO_R2` bucket, configures KV namespaces, and injects secrets like `DATAFORSEO_API_KEY` without manual dashboard configuration.

Key bindings defined in `wrangler.jsonc` include:
- **KV namespaces** for session storage and configuration
- **R2 buckets** for caching expensive API responses
- **Secret variables** such as `DATAFORSEO_API_KEY` and `POLICY_AUD`

## Edge Caching with R2 and KV

To minimize latency and reduce costs for external API calls, OpenSEO implements a caching layer using **Cloudflare R2**. API responses from DataForSEO are stored in the `dataforseo-cache/` bucket with configurable TTLs.

A lifecycle rule (configured via `wrangler r2 bucket lifecycle`) automatically expires cached objects after a specified number of days, preventing unbounded storage growth. This pattern reduces redundant API calls while maintaining fresh data.

```typescript
// Caching a DataForSEO response in R2
export async function fetchKeywordData(keyword: string, env: Env) {
  const cacheKey = `dataforseo-cache/${keyword}`;
  const cached = await env.OPEN_SEO_R2.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const fresh = await fetchFromDataForSEO(keyword, env);
  await env.OPEN_SEO_R2.put(cacheKey, JSON.stringify(fresh), {
    expirationTtl: 60 * 60 * 24, // 1 day
  });
  return fresh;
}

```

Accessing bound secrets within the Worker uses the standard environment object pattern:

```typescript
// Accessing a bound secret (DataForSEO API key)
const apiKey = env.DATAFORSEO_API_KEY;   // injected via wrangler secrets
const resp = await fetch(`https://api.dataforseo.com/v3/keyword_data?key=${apiKey}`, { … });

```

## Zero-Trust Authentication and MCP Integration

OpenSEO enforces **Zero-Trust security** through Cloudflare Access, protecting the Worker URL from unauthorized requests. Secrets including `POLICY_AUD` (Policy Audience) and `TEAM_DOMAIN` are stored in Cloudflare's Variables & Secrets dashboard and injected into the Worker environment.

For **MCP (Managed Cloud Platform)** clients, the transport layer resolves Cloudflare Access JWTs via `resolveCloudflareAccessContext` in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts). This allows CLI and desktop agents to authenticate using Managed OAuth rather than exposing raw API keys, enabling secure team collaboration.

```typescript
// Verifying Cloudflare Access JWT (used by MCP)
import { verifyJwt } from "some-jwt-lib";
export async function resolveCloudflareAccessContext(headers: Headers) {
  const token = headers.get("CF-Access-Token");
  if (!token) throw new Error("Missing Cloudflare Access token");
  const payload = await verifyJwt(token, env.POLICY_AUD);
  return payload;
}

```

## Build Optimization and Developer Experience

The build pipeline uses a custom **Vite plugin** ([`vite-plugin-lean-worker-bundle.ts`](https://github.com/every-app/open-seo/blob/main/vite-plugin-lean-worker-bundle.ts)) to produce optimized Worker bundles. This plugin strips unnecessary code and ensures compatibility with Cloudflare's JavaScript runtime, reducing bundle size and improving cold-start performance.

For local development, setting `CLOUDFLARE_INCLUDE_PROCESS_ENV=true` exposes Worker bindings as standard process environment variables. This allows the Vite dev server to mirror the Cloudflare runtime without requiring actual deployment during development.

## Summary

- **OpenSEO** deploys as a single Cloudflare Worker defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), using TanStack Start for request routing at the edge.
- **Infrastructure configuration** is managed declaratively through `wrangler.jsonc`, supporting one-click deployment with automatic secret and storage binding.
- **R2 object storage** caches expensive DataForSEO API responses in the `dataforseo-cache/` bucket with automatic lifecycle expiration.
- **Cloudflare Access** provides zero-trust authentication, with JWT verification handled in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) for secure MCP client connections.
- **Build optimization** via [`vite-plugin-lean-worker-bundle.ts`](https://github.com/every-app/open-seo/blob/main/vite-plugin-lean-worker-bundle.ts) ensures minimal bundle sizes compatible with the Cloudflare Workers runtime.

## Frequently Asked Questions

### What is the entry point for the OpenSEO Cloudflare Worker?

The entry point is [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), which exports a handler implementing `Cloudflare.WorkerEntrypoint`. This file creates a TanStack Start request handler that processes all incoming requests within the Cloudflare Workers runtime, routing them to the appropriate server functions based on the URL path.

### How does OpenSEO cache external API responses?

OpenSEO caches DataForSEO API responses in a Cloudflare R2 bucket named `dataforseo-cache/`. The Worker checks this cache before making external API calls, storing fresh results with a configurable TTL (typically 24 hours). A lifecycle rule automatically deletes expired objects to manage storage costs.

### What authentication method does OpenSEO use for MCP clients?

MCP clients authenticate via **Cloudflare Access JWTs**. The Worker validates these tokens using the `POLICY_AUD` secret against the `CF-Access-Token` header. This zero-trust approach, implemented in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts), allows team members to use Managed OAuth instead of sharing static API keys.

### How do I deploy OpenSEO to Cloudflare Workers?

Deploy by clicking the **Deploy to Cloudflare** button in the repository, which uses Wrangler to provision the Worker. Alternatively, run `wrangler deploy` locally after configuring `wrangler.jsonc` with your KV namespaces, R2 bucket (`OPEN_SEO_R2`), and secrets (`DATAFORSEO_API_KEY`, `POLICY_AUD`). The deployment automatically binds all required resources.