pseo-data

pSEO Data Architecture

Design and implement the structured data layer that feeds all programmatic SEO pages. This is the foundation every other pSEO skill depends on.

Core Principles

1. Single source of truth: All page data flows from one data layer
2. SEO-complete models: Every content model includes all fields needed for metadata, schema markup, and linking
3. Unique slugs by construction: Slug generation enforces uniqueness at the data level
4. Type safety: All data models are fully typed (TypeScript interfaces/types)
5. Separation of concerns: Data fetching is decoupled from page rendering

Data Sufficiency First

Decide which pages deserve to exist before designing anything else. Google's spam policies (scaled content abuse, doorway abuse) target many near-identical pages built mainly to rank. For every planned page type:

• Define the minimum unique data fields a page needs to be useful on its own (real facts, numbers, attributes that differ per page, not just a swapped keyword).
• Score each record against that minimum. Records below the threshold get no page: do not generate them, or return a real 404. Do not ship thin pages as noindex and plan to flip them later (a noindexed thin page still costs crawl budget and is a maintenance trap).
• Do not create a separate page for every query variation or "fan-out" query. One page per distinct entity or intent.
• Keep a clear, browseable hierarchy (category > page) so pages are not just "closer to search results" than to a site structure.

See pseo-scale for sufficiency scoring code.

Scope parameter

$ARGUMENTS source picks section 5; the optional scope limits work: models = section 1, fetching = section 2, slugs = section 3, validation = section 4, nextjs = the Next.js 16.4 section, all (default) = everything.

Implementation Steps

1. Define Content Models

Create TypeScript interfaces for each page type using a two-tier model. The lightweight index tier is safe to hold in memory for all pages; the heavy full tier is loaded per-page only.