# Open-SEO Modules Explained: 10 Core Components and Their Purposes

> Explore Open-SEO modules, the self-contained units providing SEO capabilities. Understand the 10 core components and their functions for your website.

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

---

**Open-SEO modules are self-contained feature units that expose specific SEO capabilities through server-side workflows, MCP (Machine Control Protocol) tools, and helper services wired together via a TanStack-styled API layer.**

The open-source `every-app/open-seo` repository is organized as a modular system where each business capability lives in its own folder with clean, reusable APIs. This architecture makes the codebase extensible for adding new SEO tools and portable for self-hosting on Docker or Cloudflare Workers. Below is a complete breakdown of every Open-SEO module, its purpose, and where to find the implementation.

---

## Keyword Research Module

The **Keyword Research** module generates keyword ideas, search volumes, difficulty scores, CPC data, intent classification, and related terms. It powers the UI's "Keyword research" page and exposes functionality to AI agents via the `research_keywords` MCP tool.

Core implementation lives in [`src/server/mcp/tools/research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/research-keywords.ts), which calls through to `KeywordResearchService` and ultimately the DataForSEO labs API.

```typescript
import { researchKeywordsTool } from "@/server/mcp/tools/research-keywords";

async function example() {
  const result = await researchKeywordsTool.handler({
    projectId: "proj_123",
    mode: "related",          // "related" | "suggestions" | "ideas" …
    keyword: "open source seo",
    locale: "en",
  });

  console.log(result.structuredContent?.keywords?.slice(0, 5));
}

```

---

## Rank Tracking Module

The **Rank Tracking** module periodically runs SERP lookups for keyword sets across selected devices, stores historical snapshots, and renders position graphs over time. This is implemented as two coordinated components:

- `RankCheckWorkflow` ([`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts)) — the background job scheduler
- `get_rank_tracker` MCP tool ([`src/server/mcp/tools/get-rank-tracker.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-rank-tracker.ts)) — the agent-facing API

```typescript
import { getRankTrackerTool } from "@/server/mcp/tools/get-rank-tracker";

const resp = await getRankTrackerTool.handler({
  projectId: "proj_123",
  domain: "example.com",
  scheduleInterval: "daily",
});

console.log(resp.structuredContent?.keywords);

```

The `RankTrackingService` queries the `rank_tracking` table populated by the workflow.

---

## Backlinks Module

The **Backlinks** module retrieves comprehensive backlink profiles, aggregates referring domains, and supports filtering and sorting of raw backlink rows. Two MCP tools provide layered access:

- `get-backlinks-overview` ([`src/server/mcp/tools/get-backlinks-overview.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-backlinks-overview.ts)) — high-level metrics
- `get-backlinks-profile` ([`src/server/mcp/tools/get-backlinks-profile.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-backlinks-profile.ts)) — paginated detailed rows

```typescript
import { getBacklinksOverviewTool } from "@/server/mcp/tools/get-backlinks-overview";

const { structuredContent } = await getBacklinksOverviewTool.handler({
  domain: "example.com",
});

console.log(`Backlinks: ${structuredContent?.backlinks}`);

```

Both tools route through `BacklinksService` to the DataForSEO `backlinks` endpoint.

---

## Site Audits Module

The **Site Audits** module crawls websites while respecting [`robots.txt`](https://github.com/every-app/open-seo/blob/main/robots.txt), detects SEO issues (broken links, duplicate titles, thin content), and optionally runs Lighthouse on page samples. The heavy lifting is in `SiteAuditWorkflow` ([`src/server/workflows/SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/SiteAuditWorkflow.ts)), invoked via the `site-audit-tools` MCP collection.

```typescript
import { startAudit } from "@/serverFunctions/siteAudit";

await startAudit({
  projectId: "proj_123",
  startUrl: "https://example.com",
  config: { lighthouseStrategy: "sample", maxPages: 500 },
});

```

This creates an `AuditRepository` entry and launches the workflow with configurable crawling limits.

---

## Domain Overview Module

The **Domain Overview** module provides rapid organic traffic estimates, keyword counts, and backlink summaries for any domain. It serves as the standard first step in domain research workflows.

Implementation is in [`src/server/mcp/tools/get-domain-overview.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-domain-overview.ts).

---

## SERP Retrieval Module

The **SERP Retrieval** module pulls raw Google SERP results — organic listings, local packs, and paid ads — for single queries. This supports "quick SERP peek" functionality and supplies raw ranking data to AI agents.

Found in [`src/server/mcp/tools/get-serp-results.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-serp-results.ts).

---

## Search Console Integration Module

The **Search Console Integration** module wraps Google Search Console APIs for performance reports and URL inspection. This is a **credit-free, read-only** module that does not consume DataForSEO credits.

Core files include:
- [`src/server/mcp/tools/search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/search-console-tools.ts) — MCP tool interface
- [`src/server/features/search-console/services/GscService.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/search-console/services/GscService.ts) — underlying service

```typescript
import { getSearchConsolePerformanceTool } from "@/server/mcp/tools/search-console-tools";

const { structuredContent } = await getSearchConsolePerformanceTool.handler({
  projectId: "proj_123",
  startRow: 0,
  rowCount: 20,
});

console.log(structuredContent?.rows?.[0]);

```

---

## Project and Saved Keyword Management Module

The **Project & Saved-Keyword Management** module handles CRUD operations for:
- Projects
- Saved keyword tags
- Lists of saved keywords

These are consumed by both the UI and MCP tools that reference user-persisted data. Key files:
- [`src/server/mcp/tools/list-projects.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/list-projects.ts)
- [`src/server/mcp/tools/save-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/save-keywords.ts)
- [`src/server/mcp/tools/list-saved-keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/list-saved-keywords.ts)

---

## MCP Transport Layer Module

The **MCP Transport Layer** registers all tools under a single HTTP-JSON endpoint that AI agents (Claude Code, Hermes, etc.) can call. This layer injects authentication, credit metering, and unified error handling.

Implementation: [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)

---

## Billing and Credit Features Module

The **Billing & Credit Features** module maps each SEO feature (keyword research, rank tracking, backlinks, etc.) to a credit-cost model and enforces organization-level limits.

Found in [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts)

---

## Shared Infrastructure Across All Open-SEO Modules

Every module relies on common infrastructure defined in:

- **Database schema**: [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts) — tables for projects, keywords, audits, rank-tracking runs, and credit usage
- **DataForSEO client**: [`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts) — low-level wrapper used by all paid modules
- **Error handling & telemetry**: [`src/middleware/errorHandling.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/errorHandling.ts), [`src/server/lib/posthog.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/posthog.ts) — unified logging and monitoring

---

## Summary

Open-SEO's modular architecture separates concerns into **ten distinct modules**:

- **Keyword Research** — idea generation and volume data via [`research-keywords.ts`](https://github.com/every-app/open-seo/blob/main/research-keywords.ts)
- **Rank Tracking** — scheduled SERP monitoring via [`RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/RankCheckWorkflow.ts)
- **Backlinks** — profile analysis via dual MCP tools
- **Site Audits** — crawling and Lighthouse via [`SiteAuditWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/SiteAuditWorkflow.ts)
- **Domain Overview** — quick traffic and authority snapshots
- **SERP Retrieval** — raw ranking data extraction
- **Search Console Integration** — free GSC data access
- **Project & Saved-Keyword Management** — user data persistence
- **MCP Transport Layer** — unified agent API surface
- **Billing & Credit Features** — usage metering and limits

Each module exposes clean APIs while sharing authentication, credit metering, and telemetry through the common infrastructure layer.

---

## Frequently Asked Questions

### What is an MCP tool in Open-SEO?

An **MCP (Machine Control Protocol) tool** is a standardized function that AI agents can invoke over HTTP-JSON. In Open-SEO, MCP tools wrap each SEO capability — like keyword research or rank tracking — with consistent authentication, input validation, and structured output formatting. The transport layer in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) registers all available tools for agent discovery.

### Does Open-SEO require DataForSEO credits for all modules?

**No.** Only modules that query external search data consume credits: Keyword Research, Rank Tracking, Backlinks, Site Audits, Domain Overview, and SERP Retrieval. The **Search Console Integration** module is credit-free because it reads directly from Google's APIs using stored OAuth credentials.

### How do I add a new Open-SEO module?

Create a new MCP tool file in `src/server/mcp/tools/`, implement the `handler` function with proper input/output schemas, and register it in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts). If the module needs background processing, add a workflow in `src/server/workflows/`. Finally, map credit costs in [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts) if applicable.

### Where is rank tracking data stored?

Historical rank data is stored in the `rank_tracking` database table defined in [`src/db/schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/schema.ts). The [`RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/RankCheckWorkflow.ts) populates this table on its scheduled interval, and the [`get-rank-tracker.ts`](https://github.com/every-app/open-seo/blob/main/get-rank-tracker.ts) tool queries it through `RankTrackingService` for retrieval.