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

> Discover the main building blocks of Open-SEO, a full-stack SEO platform. Explore its modular architecture including routing authentication APIs services workflows and more.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) (D1) and [`src/db/pg/schema.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/features/keywords/services/KeywordResearchService.ts)** – Handles keyword discovery and analysis
- **[`src/server/features/rank-tracking/services/RankTrackingService.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/rank-tracking/services/RankTrackingService.ts)** – Manages position tracking across search engines  
- **[`src/server/features/audit/services/AuditService.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts) manages the site-audit crawl process, while [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts) handles the nightly cron-driven rank checking operations.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/server/features/onboarding/OnboardingChatAgent.ts) provides real-time onboarding guidance, while [`src/server/features/sam/SamChatAgent.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/billing/autumn-webhook.ts), handling subscription events and quota management. For self-hosted deployments, [`src/server/lib/self-host-telemetry.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server.ts))** – Cloudflare Worker setup and request dispatching
- **Authentication ([`src/lib/auth-mode.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/auth-mode.ts))** – Multi-mode auth supporting Cloudflare Access and OAuth
- **MCP API ([`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) and [`src/db/pg/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/pg/schema.ts)
- **Repositories** – Data-access objects like [`ProjectRepository.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) (D1) and [`src/db/pg/schema.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts) manages multi-step crawl operations, while [`RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server.ts) validates credentials before dispatching to Durable Objects or API endpoints, ensuring secure access across all deployment modes.