What Are the Core Modules of Open‑SEO?

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 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

// 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. The same repository code works with SQLite (D1) or Postgres depending on runtime configuration.

The provider pattern in src/db/provider.ts resolves which concrete tables to use:

// 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, remaining agnostic to the underlying database engine.

Authentication Module

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)
• Turnstile captcha validation (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 parses the authenticated session and attaches the user and organization context to the request.

Downstream handlers in 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 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.

// 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) — Crawls sites, analyzes technical SEO issues, and stores findings
• RankCheckWorkflow (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 demonstrates the pattern:

// 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 — Health checks for self‑hosted deployments
• 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 — parsed and routed by pathname
2. MCP route → authenticated via src/lib/auth.ts, then dispatched to 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 (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) — Single Cloudflare Workers entry handling MCP, agents, and UI
• Database abstraction (src/db/schema.ts, src/db/provider.ts) — Unified schema for SQLite/Postgres
• Authentication (src/lib/auth.ts) — Better‑Auth with email, social, API key, and captcha support
• User‑context middleware (src/middleware/ensure-user/resolve.ts) — Request‑level identity resolution
• MCP server (src/server/mcp/server.ts) — AI‑agent tool registry for SEO operations
• Background workflows (SiteAuditWorkflow.ts, 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 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 applies authentication before dispatching to 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, the workflows, and database provider—assume Cloudflare APIs. Self‑hosting would require porting these platform‑specific modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}