# What Are the Core Modules of Open‑SEO?

> Explore the nine core modules of Open-SEO including server routing database abstraction authentication AI agents background workflows and more Discover its robust architecture

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

---

**The Open‑SEO architecture consists of nine core modules: server and routing, database abstraction, authentication, user‑context middleware, MCP server for AI agents, background workflows, client‑side hooks, Zod type schemas, and utility libraries.**

These modules form a clean, layered system that powers the Cloudflare Workers‑based SEO platform. Each module has a single, well‑defined responsibility and communicates through explicit interfaces. This article breaks down how each piece works, where it lives in the codebase, and how they fit together.

## Server and Routing Module

The [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) file is the single entry point for all incoming requests. It runs on Cloudflare Workers and handles three distinct traffic types:

- **MCP requests** (`/mcp` route) — AI agent tool calls
- **Chat agent routes** (`/agents/*`) — conversational SEO assistants
- **UI rendering** — TanStack React‑Start application

```typescript
// src/server.ts – fetch handler
export default {
  async fetch(request, env, ctx) {
    if (pathname.startsWith("/agents/")) {
      return routeChatAgents(request, env);
    }
    if (pathname === MCP_ROUTE) {
      return handleSelfHostedOpenSeoMcpRequest(request, authMode, env, ctx);
    }
    return appFetch(request);
  },
};

```

This module also executes scheduled **cron jobs** for recurring SEO tasks like rank tracking refreshes.

## Database Abstraction Module

Rather than maintaining separate schemas for different databases, Open‑SEO uses a unified schema in [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts). The same repository code works with **SQLite (D1)** or **Postgres** depending on runtime configuration.

The provider pattern in [`src/db/provider.ts`](https://github.com/every-app/open-seo/blob/main/src/db/provider.ts) resolves which concrete tables to use:

```typescript
// src/server/workflows/SiteAuditWorkflow.ts
await pgStep(step, "validate-context", DB_STEP, async () => {
  const audit = await AuditRepository.getAuditForWorkflow(auditId, event.instanceId);
  if (!audit) throw new Error("Audit workflow context mismatch");
});

```

`AuditRepository` and other data access layers import from [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts), remaining agnostic to the underlying database engine.

## Authentication Module

[`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts) configures **Better‑Auth** with multiple credential types:

- Email and password authentication
- Social login (OAuth providers)
- API key authentication ([`src/lib/auth-api-key.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth-api-key.ts))
- Turnstile captcha validation ([`src/lib/auth-turnstile.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth-turnstile.ts))

The module handles session creation, automatic organization bootstrapping for new users, and host‑specific secret validation for self‑hosted deployments.

## User‑Context Middleware Module

Before regular web routes serve the UI, the **ensure‑user middleware** extracts identity from request headers. [`src/middleware/ensure-user/resolve.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/ensure-user/resolve.ts) parses the authenticated session and attaches the user and organization context to the request.

Downstream handlers in [`src/middleware/ensure-user/types.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/ensure-user/types.ts) consume this context without duplicating authentication logic.

## MCP (Model‑Context‑Protocol) Server Module

The **MCP server** in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) exposes SEO tools that AI agents can invoke. It registers a catalog of capabilities including keyword research, rank tracking, site audits, and Google Analytics integration.

```typescript
// src/server/mcp/server.ts
export function createOpenSeoMcpServer(authProps: McpProps) {
  const server = new McpServer({ /* metadata */ }, { instructions: "…" });
  const register = <I extends ToolSchema>(tool: OpenSeoToolDefinition<I>) =>
    registerOpenSeoTool(server, tool, authProps);

  register(whoamiTool);
  // … additional SEO tools registered here
  return server;
}

```

Each tool definition lives in `src/server/mcp/tools/` with strongly typed input and output schemas.

## Background Workflows Module

Long‑running jobs execute inside **Cloudflare Durable Objects** via the workflows system. Two primary workflow implementations ship with Open‑SEO:

- **SiteAuditWorkflow** ([`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts)) — Crawls sites, analyzes technical SEO issues, and stores findings
- **RankCheckWorkflow** ([`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts)) — Periodically queries search engine rankings for tracked keywords

These workflows are fault‑tolerant, emit telemetry, and obtain database connections through the `withPgClient` helper.

## Client‑Side Hooks Module

The React‑based UI uses small, typed hooks for local state management. [`src/client/hooks/useDomainSearchHistory.ts`](https://github.com/every-app/open-seo/blob/main/src/client/hooks/useDomainSearchHistory.ts) demonstrates the pattern:

```typescript
// src/client/hooks/useDomainSearchHistory.ts
export function useDomainSearchHistory(projectId: string) {
  const { history, addSearch, clearHistory } = useLocalHistoryStore({
    storageKey: `domain-search-history:${projectId}`,
    maxItems: 20,
    parse: raw => domainSearchHistoryCodec.safeParse(raw).success ? raw : null,
    isSameItem: isSameSearch,
    createItem: item => ({ ...item, timestamp: Date.now() }),
    getItemKey: item => item.timestamp,
  });
  return { history, addSearch, clearHistory };
}

```

Similar hooks exist for brand lookup history and other UI state that persists across sessions in browser local storage.

## Zod Type Schemas Module

All public‑facing data structures validate at runtime using **Zod** schemas in `src/types/schemas/*.ts`. This centralizes validation for:

- Projects and organizations
- Site audits and crawl results
- Keywords and ranking data
- Backlink profiles

Shared schemas ensure type safety across server API, MCP tools, and client components.

## Utility and Library Modules

Supporting functionality lives in `src/lib/`:

- [`src/lib/selfhost-preflight.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/selfhost-preflight.ts) — Health checks for self‑hosted deployments
- [`src/lib/auth-turnstile.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth-turnstile.ts) — Bot protection integration
- Billing, telemetry, and OAuth helpers

These utilities are imported by core modules but remain loosely coupled through explicit function signatures.

## How the Modules Interact

Understanding the request flow clarifies the architecture:

1. **Request arrives** at [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) — parsed and routed by pathname
2. **MCP route** → authenticated via [`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts), then dispatched to [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)
3. **Web route** → `ensure-user` middleware resolves context, then TanStack serves the UI
4. **Data operations** → repositories use [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) (SQLite or Postgres)
5. **Background jobs** → workflow classes execute in Durable Objects with telemetry
6. **UI state** → client hooks manage local storage and call server APIs

This **thin entry point, pluggable data layer, and isolated workers** pattern keeps the codebase modular and testable.

## Summary

- **Server and routing** ([`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts)) — Single Cloudflare Workers entry handling MCP, agents, and UI
- **Database abstraction** ([`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts), [`src/db/provider.ts`](https://github.com/every-app/open-seo/blob/main/src/db/provider.ts)) — Unified schema for SQLite/Postgres
- **Authentication** ([`src/lib/auth.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth.ts)) — Better‑Auth with email, social, API key, and captcha support
- **User‑context middleware** ([`src/middleware/ensure-user/resolve.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/ensure-user/resolve.ts)) — Request‑level identity resolution
- **MCP server** ([`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)) — AI‑agent tool registry for SEO operations
- **Background workflows** ([`SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts), [`RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/RankCheckWorkflow.ts)) — Fault‑tolerant Durable Object jobs
- **Client‑side hooks** (`src/client/hooks/`) — Typed React hooks for local UI state
- **Zod schemas** (`src/types/schemas/*.ts`) — Centralized runtime validation
- **Utility libraries** (`src/lib/`) — Billing, telemetry, self‑host checks, and helpers

## Frequently Asked Questions

### What database does Open‑SEO support?

Open‑SEO supports **both SQLite (Cloudflare D1) and Postgres** through a single abstracted schema. The [`src/db/provider.ts`](https://github.com/every-app/open-seo/blob/main/src/db/provider.ts) module determines at runtime which concrete implementation to use, so the same repository code works with either database without modification.

### How does Open‑SEO authenticate AI agents?

AI agents authenticate through the **MCP server module** using the same Better‑Auth system as human users. The `handleSelfHostedOpenSeoMcpRequest` function in [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts) applies authentication before dispatching to [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), where tools validate organization and permission context.

### What makes the background workflows fault‑tolerant?

The **workflow module** leverages **Cloudflare Durable Objects** with `pgStep` helper functions that wrap database operations. If a step fails, the Durable Object automatically retries with backoff. Telemetry events track execution state, and the workflow state persists across invocations.

### Can I self‑host Open‑SEO without Cloudflare?

The codebase is optimized for Cloudflare Workers, D1, and Durable Objects. While the modular architecture separates concerns cleanly, significant portions—particularly [`src/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server.ts), the workflows, and database provider—assume Cloudflare APIs. Self‑hosting would require porting these platform‑specific modules.