# Product Specification — North West SEO

Automated SEO Management Platform for local businesses, car dealerships,
service businesses, ecommerce, multi-location companies and agencies.
Production: `https://seo.northwestcar.group`. Brand name and URL are
environment-configurable for future white-labelling.

## What it does

Connects to a customer's website, audits its SEO, explains problems in plain
English, and prepares improvements that are **always recorded, approved where
appropriate, and reversible**.

Capability areas (full list mirrors the master brief):
crawling & sitemap discovery · technical issue detection · titles/descriptions/
headings analysis · broken links & redirects · duplicate/thin content ·
keyword research/clustering/tracking · GSC + GA4 import · competitor analysis ·
content briefs & AI-assisted content · page optimisation · internal linking ·
structured data · local SEO & location pages · programmatic SEO with
safeguards · sitemap/robots/redirect management · monitoring · reporting ·
agency multi-client support.

Supported site platforms: WordPress, Shopify, Webflow, WooCommerce, custom
PHP, Laravel, Next.js, static HTML, custom APIs, sitemap-only monitoring.

## Hard product rules

- No fabricated metrics, rankings, volumes, traffic or competitor data.
  Unavailable = shown as unavailable; estimates clearly labelled.
- No guaranteed-ranking or guaranteed-revenue claims anywhere.
- No cloaking, hidden text, doorway pages, link spam, or ToS-violating
  SERP scraping.
- Never silently change a customer website; every change stores the original
  and is reversible; regulated/legal pages are never edited automatically.
- Failures are visible with recovery paths; unfinished features are never
  presented as complete.

## Roles

Platform administrator · Organisation owner · Organisation admin ·
SEO manager · Content editor · Reviewer · Read-only. (RBAC matrix in
`src/lib/auth/rbac.ts`; tested.)

## Approval modes

Recommendation / Approval / Automatic — configurable at organisation and
website level (schema in place), later per content-type/change-type/URL
pattern. Regulated content defaults to Approval.

## Status by phase

| Phase | Scope | Status |
| --- | --- | --- |
| 1 Foundation | auth, organisations, RBAC, websites, verification, schema, logging, dashboard, tests, env/docker | **Delivered** (2FA UI pending — tracked) |
| 2 Crawler & audit | SSRF-safe crawler, queue, progress, cancellation, issue detection | **Core delivered**; sitemap ingestion, SEO score, crawl comparison in progress |
| 3 Search data | GSC, GA4, keywords, clustering, rank provider interface | Schema ready; not started |
| 4 AI content | provider abstraction, brand profiles, briefs, drafts, quality checks | Schema ready; not started |
| 5 Publishing | connector interface, WordPress, approvals, rollback | Schema ready; not started |
| 6 Advanced SEO | internal links, structured data, sitemaps, robots, redirects, local SEO, competitors | Schema ready; not started |
| 7 Commercial | Stripe, limits, reports, notifications, agency tools, admin | Schema ready; not started |

## Acceptance criteria style

Every feature ships only when it works end-to-end against real data, with
permissions + tenant isolation enforced, errors/loading/empty states handled,
tests/typecheck/lint green, docs updated, and audit logging in place
(Definition of Done, master brief §68).

## Verification checklist (production)

The deploy checklist lives in DEPLOYMENT.md §22–24 and mirrors the master
brief §69 — registration through crawl cancellation, cookie security, no
localhost/staging URLs, health endpoint, tenant-isolation and SSRF tests
passing.

## Demonstration data

Optional, removable seed (`npm run db:seed`): fictional "North West Vehicle
Centre" dealership in Lancashire with brand profile, one location (service
areas: Kirkham, Preston, Blackpool, Lytham St Annes, Poulton-le-Fylde,
Fleetwood, Garstang, Chorley, Leyland, Lancaster, Southport) and four demo
keywords **with null metrics** (nothing fabricated). Nothing in platform
logic depends on it.