Rolling page health

How VisualQ computes site and page quality scores from fresh audits — coverage, freshness, and partial runs.

VisualQ uses a rolling health model. A site score is never copied from a single run — it aggregates fresh per-page scores across all audited pages.

Two levels — never conflate them

Level	Question	Storage	UI surfaces
Page	How is this page on pillar X?	`page_health/{pageId}`	Page detail, pillar page tables
Site	How is the project on pillar X?	`site_health/summary`	Overview, pillar KPI headers, quality score

Freshness and coverage

Stale threshold: 30 days by default. Pages older than this are excluded from site aggregates and marked stale in the UI.
Site pillar score: mean of per-page scores where the pillar audit is fresh (< 30 days).
Coverage is always visible at site level — e.g. 67% coverage · 8/12 pages. A site score without coverage context is misleading.

Stale and never-audited pages are excluded from the mean but counted in coverage.

Which pillars use page health?

Seven page pillars roll up into page_health:

visual, a11y, perf, seo, security, tracking, privacy

Functional (FRT) is separate — it uses frt_health/summary because journeys are not VRT page scenarios. The overview shows both site health and FRT health.

Partial runs

Auditing 1 of 12 pages updates only that page's page_health entry, then recomputes site_health. Never copy a single-page score to represent the whole site without aggregation.

On run completion, VisualQ calls persistPageHealthAfterRun before syncing the composite quality score. Every pillar run must feed page health extraction when applicable.

Quality score source

The project quality score comes from rolling page health (syncQualityScoreFromSiteHealth), not from latestA11yRun or any single latest-run field.

Agents must use get_site_health or gate_pr_quality for project KPIs — never treat one VRT or a11y run as the site score.

Firestore paths

organizations/{orgId}/projects/{projectId}/
  page_health/{pageId}   — pillars.{visual|a11y|perf|seo|security|tracking|privacy}
  site_health/summary    — aggregated rollups + pages[] snapshot
  frt_health/summary     — functional pillar rollup

API

GET /api/projects/{projectId}/health

Returns site rollups, per-page freshness, and coverage percentages for each pillar.

Backfill

If you migrated from an older model or need to rebuild aggregates:

POST /api/projects/{projectId}/health/backfill

Requires an authenticated session with project access.

On this page