🚀 Architecture & Measurement Engine
PageSpeedIQ is an open, accurate performance diagnostic suite designed to deliver authentic lab measurements and real-user Web Vitals without synthetic approximations or fabricated score formulas.
Accuracy Principle: Every displayed score, metric value, and opportunity traces directly to a real audit provider. If a provider cannot reach or analyze a URL, the tool displays an honest error rather than estimating artificial scores.
- Dual-Provider Lab Engine: Executes via local Google Lighthouse (v13.5.0) where server runtime supports Node.js and headless Chromium, and seamlessly uses Google's PageSpeed Insights API (v5) for keyless shared hosting deployments.
- Real Chrome UX Report (CrUX) Field Data: Displays 28-day aggregate real-user experiences for URLs and Origins when data is present in CrUX, or clearly states when field traffic is insufficient.
- Single Canonical Source of Truth: Top summary gauges, category cards, score calculators, and export badges all read from one normalized score scale (0–100).
- Server-Side Security (SSRF Protection): Strict validation resolves domain names and rejects loopback, private, link-local, and reserved IP ranges to protect infrastructure.
- Interactive Waterfall: Renders genuine network request timelines, asset mime-types, status codes, and transfer sizes from measured audits.
- Stable Report Snapshots: Audit runs generate persistent snapshot IDs (
?id=<snapshotId>) allowing teams to share and revisit reports without re-running audits.
📖 How the Audit Pipeline Operates
When a user initiates an audit in includes/Analyzer.php, the request follows a strict verification flow:
- URL Validation & Normalization: Confirms public HTTP/HTTPS scheme and standard ports (80, 443, 8080, 8443).
- SSRF Verification: Performs DNS resolution and validates that resolved IPv4 and IPv6 addresses are public and safe.
- Provider Selection:
- If local Node.js and headless Chrome are available, runs
includes/run-lighthouse.mjs. - Otherwise, connects to Google's official PageSpeed Insights API (v5). Optional
GOOGLE_PSI_API_KEYis supported for higher volume environments.
- If local Node.js and headless Chrome are available, runs
- Metric Extraction: Parses raw JSON audits into standardized canonical schemas for Performance, Accessibility, Best Practices, and SEO.
- Snapshot Persisted: Saves full report payload to
cache/snapshots/with unique ID for immutable share links.
⚡ Core Web Vitals Reference
Core Web Vitals are standardized performance metrics defined by Google and the Chromium project to assess user experience:
1. Largest Contentful Paint (LCP)
Good: ≤ 2.5 s Needs Improvement: 2.5 s – 4.0 s Poor: > 4.0 s
Measures perceived loading speed. LCP marks when the main hero image or largest textual block is completely rendered in the viewport.
2. Interaction to Next Paint (INP)
Good: ≤ 200 ms Needs Improvement: 200 ms – 500 ms Poor: > 500 ms
Measures page responsiveness to user clicks, taps, and keypresses. INP tracks the overall latency from user input until the next frame is presented on screen.
3. Cumulative Layout Shift (CLS)
Good: ≤ 0.10 Needs Improvement: 0.10 – 0.25 Poor: > 0.25
Measures visual stability. CLS quantifies unexpected movements of page content while loading (e.g. late-loading banner ads or unsized images shifting paragraphs).
4. Total Blocking Time (TBT)
Good: ≤ 200 ms Needs Improvement: 200 ms – 600 ms Poor: > 600 ms
Lab proxy for interactivity. TBT measures the total amount of time between First Contentful Paint and Time to Interactive where the browser main thread was blocked by tasks exceeding 50 ms.
5. First Contentful Paint (FCP)
Good: ≤ 1.8 s Needs Improvement: 1.8 s – 3.0 s Poor: > 3.0 s
Marks the point when the browser renders the first piece of DOM content (text, canvas, or non-white svg/image).