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

> Discover the main entry point for the Open-SEO project at src/server.ts. Learn how it handles fetch and scheduled handlers for Cloudflare Workers.

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

---

**The main entry point for the Open-SEO project is [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), which exports the `fetch` and `scheduled` handlers that Cloudflare Workers invokes for every HTTP request and cron-based rank-checking job.**

The every-app/open-seo repository is a Cloudflare Workers application built on TanStack React-Start that powers SEO auditing, SERP rank tracking, and AI chat agent routing. Identifying the main entry point for the Open-SEO project is critical for debugging request flows, extending middleware, or customizing worker behavior for custom deployments.

## The Primary Entry Point: [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)

Cloudflare Workers requires a single module that exports specific handler functions. In the Open-SEO codebase, **[`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)** serves as this contract point with the Workers runtime.

The file exports two critical handlers:

- **`fetch`**: Handles all incoming HTTP requests and routes them to the appropriate sub-system.
- **`scheduled`**: Executes cron-triggered background jobs for periodic rank checking.

### The Fetch Handler

The `fetch` export is the primary request processor. According to the source code in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), this function wraps the request handling with database connection management and delegates to specialized routers based on the URL pathname.

```typescript
// src/server.ts (excerpt)
import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";
import { routeAgentRequest } from "agents";
import { resolveUserContextFromHeaders } from "@/middleware/ensure-user/resolve";

const appFetch = createStartHandler(defaultStreamHandler);
const openSeoOAuthProvider = createOpenSeoOAuthProvider(appFetch);

function fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
  // Cloudflare Workers call this function for every incoming request.
  // It delegates to the appropriate sub‑router based on pathname.
  return withPgClient(() => Promise.resolve(handleFetch(request, env, ctx)));
}

```

Inside `handleFetch`, the request is routed to:
- The TanStack React-Start handler (`appFetch`) for server-rendered routes.
- The OAuth provider for authentication flows.
- Self-hosted MCP (Model Context Protocol) endpoints.
- Chat agent routes handled by the `routeAgentRequest` function.

### The Scheduled Handler

The `scheduled` export handles cron-triggered executions configured in [`wrangler.toml`](https://github.com/every-app/open-seo/blob/main/wrangler.toml). This handler triggers the **RankCheckWorkflow** for periodic SERP position monitoring and the **SiteAuditWorkflow** for automated SEO auditing. Both workflow classes are defined in [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts) and [`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts) but are re-exported through [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) to maintain a clean public API for the Worker.

## Request Routing and Middleware Initialization

While [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) acts as the runtime entry point, it coordinates with initialization logic defined elsewhere. The actual TanStack React-Start configuration—including CSRF protection middleware and global server-function middleware—resides in **[`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)**.

### [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) vs [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)

The distinction between these files is architectural:

- **[`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)**: Contains the `createStart` call that configures the TanStack React-Start framework, sets up the default stream handler, and attaches global middleware. This file is imported by [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) but is not the Workers entry point.
- **[`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)**: Imports the configured app from [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) and exports the handlers required by the Cloudflare Workers runtime. The [`wrangler.toml`](https://github.com/every-app/open-seo/blob/main/wrangler.toml) configuration points specifically to this file.

This separation allows the framework initialization to remain isolated from the platform-specific handler exports required by Cloudflare's runtime.

## Workflow Exports and Server Functions

Beyond request handling, [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) serves as the aggregation point for background job workflows. The file re-exports:

- **SiteAuditWorkflow** from [`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts)
- **RankCheckWorkflow** from [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts)

These exports enable the Workers runtime to instantiate workflow classes directly when triggered by the `scheduled` handler or by durable object alarms. Health check endpoints, such as those defined in [`src/routes/api/health.ts`](https://github.com/every-app/open-seo/blob/main/src/routes/api/health.ts), are accessible through the TanStack router initialized in [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) but are ultimately served through the `fetch` handler in the entry point.

## Summary

- **[`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)** is the main entry point for the Open-SEO project, exporting the `fetch` and `scheduled` handlers required by Cloudflare Workers.
- The `fetch` handler routes HTTP requests to TanStack React-Start, OAuth providers, MCP endpoints, or chat agents based on the request path.
- **[`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts)** handles framework initialization and middleware setup but is not the runtime entry point.
- Background workflows for SEO auditing and rank checking are re-exported through [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) for cron-triggered execution.
- The entry point uses `withPgClient` to wrap requests with PostgreSQL connection management.

## Frequently Asked Questions

### Is [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) the main entry point for Open-SEO?

No. While [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts) initializes the TanStack React-Start framework and configures middleware, the actual Cloudflare Workers entry point is [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts). The Workers runtime loads [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) based on the `main` field in [`wrangler.toml`](https://github.com/every-app/open-seo/blob/main/wrangler.toml), which then imports the configured application from [`src/start.ts`](https://github.com/every-app/open-seo/blob/main/src/start.ts).

### What handlers must [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) export for Cloudflare Workers?

The file must export a `fetch` handler for HTTP requests and a `scheduled` handler for cron jobs. The `fetch` function accepts `Request`, `Env`, and `ExecutionContext` parameters, while `scheduled` handles background execution triggers for workflows like `RankCheckWorkflow`.

### How does the entry point handle database connections?

The `fetch` handler wraps request processing with `withPgClient()`, a utility that manages PostgreSQL connection pooling. This ensures each request has access to the database client through the execution context while properly handling connection cleanup.

### Can I add custom API routes by modifying the entry point?

While you can modify routing logic in the `handleFetch` function within [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), the recommended approach is to add routes through the TanStack React-Start file-based routing system in `src/routes/`. For example, adding a file to `src/routes/api/` automatically registers the endpoint through the `appFetch` handler without requiring changes to the entry point file.