Build an SEO Automation System

reference-seo-system/
  app/api/cron/content/
    discovery/route.js      # scheduled opportunity discovery
    worker/route.js         # advance one due workflow step
  app/blog/[slug]/page.js   # render published articles
  src/seo/
    orchestrator.js         # lease a workflow and run one bounded step
    state-machine.js        # legal transitions for the reference flow
    repository.js           # leases, budgets and circuit breakers
    discovery.js            # demand discovery, scoring and deduplication
    research.js             # evidence retrieval and verification
    structured-output.js    # schema-constrained model calls
    policy.js               # automatic publication and lifecycle gates
    monitoring.js           # outcome checks and lifecycle signals
    search-console.js       # indexing and performance measurements
    *.test.js               # regression suites beside the modules
  hosting-config.example    # runtime schedules and resource limits

# Educational reference dependencies. Choose versions that match
# your application and review their official documentation.
npm install next react react-dom pg

# pg       -> reference Postgres repository
# Hosting  -> deploy to a Web Hoster / Cloud Infrastructure

# .env.example — placeholder values only; never commit real secrets
DATABASE_URL=postgres://user:password@host:5432/database
MODEL_GATEWAY_API_KEY=replace_with_server_side_secret
CONTENT_CRON_SECRET=replace_with_random_bearer_token
CONTENT_DAILY_NEW_PAGE_LIMIT=replace_with_integer
CONTENT_MAX_MODEL_CALLS_PER_WORKFLOW=replace_with_integer
CONTENT_POLICY_VERSION=replace_with_version_identifier

-- Illustrative reference schema; adapt names to your system.
create table content_topics (
  id uuid primary key,
  query text not null,
  locale text check (locale in ('en','ar')),
  intent text,
  canonical_topic text,
  priority_score numeric
);

create table content_workflows (
  id uuid primary key,
  topic_id uuid references content_topics(id),
  current_state text not null,
  intended_action text,
  retry_count int default 0,
  failure_category text,
  idempotency_key text unique,
  locked_at timestamptz,
  next_review_at timestamptz
);

create table content_evidence_sources (
  id uuid primary key,
  workflow_id uuid references content_workflows(id),
  url text not null,
  publisher text,
  retrieved_at timestamptz,
  excerpt text,
  verification_status text      -- verified | retired
);

create table content_validation_results (
  workflow_id uuid,
  stage text,                   -- CLAIM | QUALITY | SEO | PUBLICATION
  decision text,                -- pass | repair | reject
  details jsonb
);

-- Every factual clause must map to retrieved evidence.
-- Unsupported clauses route to REPAIRING, never to publication.

// src/seo/state-machine.js — educational reference example
export const WORKFLOW_STATES = Object.freeze([
  "DISCOVERED", "ELIGIBILITY_CHECK", "CLUSTERING",
  "EXISTING_CONTENT_CHECK", "RESEARCHING", "EVIDENCE_READY",
  "BRIEF_GENERATING", "BRIEF_READY", "DRAFTING", "DRAFTED",
  "CLAIM_VALIDATION", "QUALITY_VALIDATION", "SEO_VALIDATION",
  "REPAIRING", "READY_TO_PUBLISH", "PUBLISHING", "PUBLISHED",
  "MONITORING", "REFRESH_REQUIRED", "MERGE_REQUIRED",
  "REDIRECT_REQUIRED", "NOINDEX_REQUIRED", "REJECTED",
  "FAILED_RETRYABLE", "FAILED_FINAL"
]);

assertTransition("DRAFTED", "CLAIM_VALIDATION"); // allowed
assertTransition("DRAFTED", "PUBLISHED");        // throws

// A scheduler on your Web Hoster / Cloud Infrastructure invokes
// this worker. One lease, one bounded step, then release.
export async function runContentWorker() {
  const workflow = await claimNextDueWorkflow();
  if (!workflow) return { ok: true, idle: true };

  try {
    await advanceOneStep(workflow);
  } catch (error) {
    await recordFailure(workflow, error); // backoff + circuit breaker
  }
  return { ok: true, workflowId: workflow.id };
}

// Compare locale, intent, canonical cluster and similarity
// before drafting. This function is deterministic and testable.
export function decideIntendedAction({ topic, livePages }) {
  const sameCluster = livePages.filter((page) =>
    page.locale === topic.locale &&
    page.canonicalTopic === topic.canonicalTopic
  );

  if (sameCluster.some((p) => p.coverage === "strong")) return "REJECT_TOPIC";
  if (sameCluster.some((p) => p.coverage === "partial")) return "REFRESH_EXISTING";
  if (sameCluster.length > 1) return "MERGE_INTO_EXISTING";
  return "CREATE_NEW";
}

// Re-extract every factual clause and verify the exact text
// against stored evidence instead of relying on model memory.
export async function validateClaims(workflowId, draft) {
  const evidence = await getVerifiedEvidence(workflowId);

  return extractClaims(draft).map((claim) => ({
    ...claim,
    status: evidence.some((row) =>
      claim.evidenceIds.includes(row.id) &&
      supportsExactClause(row.excerpt, claim.text)
    ) ? "supported" : "unsupported"
  }));
}

{
  "workflow_id": "wf_reference_topic_en",
  "current_state": "SEO_VALIDATION",
  "intended_action": "CREATE_NEW",
  "locales": ["en", "ar"],
  "gates": {
    "claims": "pass",
    "quality": "pass",
    "seo": "pending",
    "publication_policy": "pending"
  },
  "retry_count": 0,
  "failure_category": null,
  "publishable": false
}

// app/api/cron/content/worker/route.js — simplified reference
export async function GET(request) {
  const token = request.headers.get("authorization");
  if (token !== "Bearer " + process.env.CONTENT_CRON_SECRET) {
    return Response.json({ error: "unauthorized" }, { status: 401 });
  }

  const result = await runContentWorker();
  return Response.json(result);
  // A revision is published automatically only after every policy signal
  // passes and the public URL is verified. Otherwise it repairs or stops.
}

// Illustrative regression cases for the reference implementation.
const cases = [
  ["illegal state transition", "throws"],
  ["unsupported factual clause", "REPAIRING"],
  ["duplicate intent detected", "MERGE_REQUIRED"],
  ["provider fails repeatedly", "circuit_breaker_open"],
  ["all publication signals pass", "PUBLISHED"],
  ["public URL verification fails", "automatic_rollback"],
  ["overlap exceeds merge threshold", "automatic_merge_queued"],
  ["lifecycle evidence is incomplete", "action_blocked"]
];

test.each(cases)("%s -> %s", async (scenario, expected) => {
  expect(await runFixture(scenario)).toEqual(expected);
});