Main Building Blocks of Open-SEO: A Full-Stack SEO Platform Architecture

Open-SEO is organized as a set of clearly-separated modules that together provide a full-stack SEO platform, including an entry point router, authentication layer, MCP API, database abstraction, repositories, feature services, workflows, chat agents, and billing components.

Open-SEO is a comprehensive SEO platform built to run on Cloudflare Workers. Understanding its modular architecture is essential for developers looking to extend functionality, debug issues, or deploy self-hosted instances. The codebase follows clean separation of concerns with distinct layers handling routing, data persistence, business logic, and real-time communication.

Entry Point and Request Routing

The application bootstraps in src/server.ts, which sets up the Cloudflare Worker and handles all incoming HTTP requests. This entry point is responsible for authorizing chat agents and dispatching requests to the appropriate sub-systems. It serves as the central traffic controller that decides whether a request should be handled by the MCP API layer, a Durable Object, or the authentication system.

Authentication and Access Control

Open-SEO supports multiple authentication strategies through the configuration defined in src/lib/auth-mode.ts. The platform supports Cloudflare Access for enterprise deployments, a local no-auth mode for development, and an internal OAuth provider used for self-hosted deployments. Runtime flags in this module determine which authentication mode is active, allowing the same codebase to run in different environments without modification.

MCP API Layer for Frontend Communication

The Machine-Client-Protocol (MCP) API exposes a typed JSON-RPC-like interface that the frontend uses to invoke server-side tools. The transport layer in src/server/mcp/transport.ts handles serialization and communication, while individual tools live in src/server/mcp/tools/**. This layer exposes functionality like project creation, SERP data retrieval, and keyword research through a structured, versioned interface.

// Example: Creating a new project via the MCP API
import { createOpenSeoOAuthProvider } from "@/server/mcp/oauth-provider";

const provider = createOpenSeoOAuthProvider(appFetch);
await provider.fetch(request, env, ctx);

Database Abstraction with Drizzle ORM

The database layer uses Drizzle-ORM with dual dialect support: SQLite/D1 for development and PostgreSQL for production. Schemas are defined in src/db/schema.ts (D1) and src/db/pg/schema.ts (PostgreSQL), providing type-safe database access. This abstraction allows developers to run locally against SQLite while deploying to Cloudflare's D1 or a Postgres instance in production without changing application code.

Repository Pattern for Data Access

Repositories are thin data-access objects that encapsulate SQL queries for each domain. Located under src/server/features/**/repositories/, these classes abstract the raw database implementation details. For example, src/server/features/projects/repositories/ProjectRepository.ts handles all project-related persistence logic, keeping the business logic in services free from SQL concerns.

Feature Services for SEO Logic

The business-logic layer implements core SEO capabilities through isolated service classes in src/server/features/. Each feature domain maintains its own folder containing services, repositories, and types:

• src/server/features/keywords/services/KeywordResearchService.ts – Handles keyword discovery and analysis
• src/server/features/rank-tracking/services/RankTrackingService.ts – Manages position tracking across search engines
• src/server/features/audit/services/AuditService.ts – Performs site health checks and technical SEO audits

Additional features include GSC integration, backlink analysis, and AI-search capabilities, each following the same organizational pattern.

Workflow Orchestration for Background Jobs

Long-running, multi-step processes are orchestrated through a step-based workflow pattern. These workflows can run both in-process and as background jobs, handling tasks like comprehensive site crawls and scheduled rank checks.

The src/server/workflows/SiteAuditWorkflow.ts manages the site-audit crawl process, while src/server/workflows/RankCheckWorkflow.ts handles the nightly cron-driven rank checking operations.

// Example: Running a rank-check workflow (invoked by the nightly cron)
import { runScheduledRankChecks } from "@/server/features/rank-tracking/services/scheduledRankChecks";

await withPgClient(() => runScheduledRankChecks(env));

Real-Time Chat Agents via Durable Objects

Open-SEO implements conversational assistants using Cloudflare Durable Objects. The src/server/features/onboarding/OnboardingChatAgent.ts provides real-time onboarding guidance, while src/server/features/sam/SamChatAgent.ts implements the SAM (Self-Assist-Mate) functionality. Authorization for these WebSocket connections is performed in the Worker before the Durable Object receives the connection, ensuring secure access control.

Billing and Telemetry Integration

The platform integrates with Autumn for usage-based billing through src/server/billing/autumn-webhook.ts, handling subscription events and quota management. For self-hosted deployments, src/server/lib/self-host-telemetry.ts sends heartbeat telemetry to monitor instance health and usage patterns without compromising privacy.

Summary

• Entry Point (src/server.ts) – Cloudflare Worker setup and request dispatching
• Authentication (src/lib/auth-mode.ts) – Multi-mode auth supporting Cloudflare Access and OAuth
• MCP API (src/server/mcp/transport.ts) – Typed JSON-RPC interface for frontend communication
• Database Layer – Drizzle-ORM with SQLite/D1 and PostgreSQL support via src/db/schema.ts and src/db/pg/schema.ts
• Repositories – Data-access objects like ProjectRepository.ts encapsulating SQL logic
• Feature Services – Domain-specific business logic for keywords, rank tracking, and audits
• Workflows – Background job orchestration for crawls and cron jobs
• Chat Agents – Durable Object-based real-time assistants for onboarding and support

Frequently Asked Questions

What database does Open-SEO use?

Open-SEO uses Drizzle-ORM with support for two database dialects: SQLite/D1 for development and local deployments, and PostgreSQL for production environments. The schemas are defined in src/db/schema.ts (D1) and src/db/pg/schema.ts (Postgres), allowing seamless switching between backends without modifying application logic.

How does Open-SEO handle background tasks like site audits?

Long-running processes are handled by the workflow system using step-based orchestration. The SiteAuditWorkflow.ts manages multi-step crawl operations, while RankCheckWorkflow.ts handles scheduled position checks. These workflows can run both in-process and as background jobs, invoked by cron triggers or manual requests.

What is the MCP API in Open-SEO?

The Machine-Client-Protocol (MCP) API is a typed JSON-RPC-like interface exposed through src/server/mcp/transport.ts. It provides a structured contract between the frontend and backend, allowing the UI to call server-side tools for project management, keyword research, and SERP data retrieval with full type safety.

How is authentication implemented for self-hosted deployments?

Open-SEO supports multiple authentication modes controlled by runtime flags in src/lib/auth-mode.ts. For self-hosted instances, it includes an internal OAuth provider alongside support for Cloudflare Access. The entry point in src/server.ts validates credentials before dispatching to Durable Objects or API endpoints, ensuring secure access across all deployment modes.

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