# What Is the Main Entry Point for the Open-SEO Application?

> Discover the main entry point for the Open-SEO application, the fetch export in src/server.ts. Learn how Cloudflare Workers leverage this serverless function to manage incoming HTTP requests.

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

---

**The main entry point for the Open-SEO application is the `fetch` export defined in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), which Cloudflare Workers invoke to handle every incoming HTTP request.** This serverless function acts as the central orchestrator, routing traffic between the TanStack React-Start handler, OAuth flows, and specialized endpoints like MCP servers and agent workflows.

Open-SEO is architected as a Cloudflare Worker, meaning the platform expects a default export containing specific handler functions. According to the `every-app/open-seo` source code, the `fetch` method in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) serves as this primary interface, wrapping the TanStack Start framework with custom runtime logic for database connections and route-specific middleware.

## The Cloudflare Worker Entry Point Architecture

Cloudflare Workers look for a default exported object containing lifecycle methods. In [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), this export exposes both `fetch` (for HTTP requests) and `scheduled` (for cron triggers):

```typescript
// src/server.ts
import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";

const appFetch = createStartHandler(defaultStreamHandler);

export default {
  fetch,               // ← Cloudflare invokes this as the entry point
  async scheduled(event, env, ctx) {
    // Cron job handling logic
  }
};

```

When a request hits the Worker, Cloudflare automatically executes the `fetch` function, passing the standard Worker parameters: `request`, `env`, and `executionCtx`. This design pattern ensures that **all traffic flows through a single, controllable gateway** before reaching application logic.

## How the Request Handler Orchestrates Traffic

Inside [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), the `fetch` implementation delegates to an internal `handleFetch` function that performs three critical operations before serving responses:

1. **Database Context Initialization**: Wraps the request with `withPgClient` to establish a per-request Postgres client, ensuring database connections are properly scoped and cleaned up.
2. **Special Route Handling**: Intercepts specific paths including `/agents/*`, Autumn webhook endpoints, and self-hosted MCP (Model Context Protocol) servers.
3. **Application Fallback**: Routes standard page requests to the TanStack React-Start handler (`appFetch`) for server-side rendering and API calls.

The `handleFetch` implementation effectively creates a middleware layer that preprocesses requests before they reach the React application layer. This architecture allows Open-SEO to handle both traditional web traffic and specialized API endpoints within the same serverless function.

## Distinguishing Between Configuration and Entry Point

Developers often confuse [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) with the application entry point because it handles framework configuration. However, [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) merely defines the TanStack Start instance used by the handler, not the Worker entry point itself:

```typescript
// src/start.ts
import { createCsrfMiddleware, createStart } from "@tanstack/react-start";

const csrfMiddleware = createCsrfMiddleware();

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware],
  functionMiddleware: globalServerFunctionMiddleware,
}));

```

While [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) exports the configuration consumed by `createStartHandler`, **Cloudflare never directly invokes this file**. Instead, [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) imports this configuration during initialization, creating a clear separation between framework setup and request handling orchestration.

## Extending the Entry Point with Custom Routes

You can extend the main entry point to handle custom API endpoints by modifying the `handleFetch` logic before it delegates to `appFetch`. This approach is useful for health checks or lightweight endpoints that don't require the full React-Start initialization:

```typescript
// Example: Adding a health check endpoint inside handleFetch
if (pathname === "/api/health") {
  return new Response(JSON.stringify({ status: "ok", timestamp: Date.now() }), {
    headers: { "Content-Type": "application/json" },
    status: 200,
  });
}

```

For testing purposes, you can manually invoke the entry point using standard ES module imports:

```typescript
// Manual invocation for integration testing
import server from "./src/server";

const response = await server.fetch(
  new Request("https://example.com/api/health"), 
  {} as any, 
  {} as any
);

```

## Summary

- **The primary entry point** for Open-SEO is the `fetch` export in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), invoked automatically by Cloudflare Workers for every HTTP request.
- **Request orchestration** happens through `handleFetch`, which initializes Postgres clients, handles agent/MCP routes, and falls back to TanStack React-Start for standard requests.
- **Configuration separation** exists between [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) (framework setup) and [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) (request handling), with only the latter serving as the Worker entry point.
- **Extensibility** is built into the architecture, allowing developers to intercept requests before they reach the React application layer for custom API endpoints or authentication logic.

## Frequently Asked Questions

### What file does Cloudflare Workers use as the entry point for Open-SEO?

Cloudflare Workers use [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) as the entry point, specifically looking for the default exported object containing the `fetch` function. This is defined by the Cloudflare Workers runtime specification, which automatically invokes this method when HTTP requests arrive at the edge.

### How does Open-SEO handle routing for special endpoints like webhooks and MCP servers?

The `handleFetch` function in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) checks the request pathname against specific patterns (such as `/agents/*` or Autumn webhook routes) before falling back to the TanStack React-Start handler. This allows the application to handle specialized server-to-server communication without loading the full React rendering pipeline.

### What is the difference between [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) and [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) in the Open-SEO codebase?

[`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) is the Cloudflare Worker entry point that exports the `fetch` handler invoked by the runtime, while [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) configures the TanStack Start framework instance (`createStart`) with CSRF middleware and server-function middleware. The entry point imports the start configuration, but Cloudflare never directly executes [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts).

### Can I add custom API routes without modifying the TanStack React-Start router?

Yes. You can extend the `handleFetch` function in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) to intercept specific paths (like `/api/health` or custom webhooks) and return `Response` objects directly before the request reaches the `appFetch` handler. This pattern is ideal for lightweight endpoints that require minimal overhead or need to bypass React-Start's rendering logic entirely.