Page Speed Monitoring

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/page-speed-monitoring/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A page-speed monitoring system that measures Core Web Vitals (LCP, FID, CLS) and alerts merchants when speed degrades, with optional performance budgets.

The problem

Merchants don’t know if their site is slow; a 3-second page load means 40% fewer conversions, but they’re unaware.

What it does

• Measure page load time (from first request to DOM interactive or full page load)
• Track Core Web Vitals (LCP, FID, CLS) per Google PageSpeed standards
• Display speed metrics in admin dashboard (sparkline, trend)
• Alert if speed degrades (e.g., slow request spike)
• Identify slow pages (top 10 slowest pages)
• Performance budget: set threshold (e.g., ‘LCP must be < 2.5s’), alert if breached
• Export metrics as JSON (for third-party tools)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Auto-optimization — we don’t automatically fix slow pages. Reason: optimization requires code changes.
• Third-party service monitoring — we don’t monitor external CDN/analytics providers. Reason: outside our control.
• User experience analytics — no heatmaps or session replay. Reason: that’s paid feature (content-performance-analytics).

Data model

New tables: PageSpeedMetric {id, pageUrl, timestamp, lcp (ms), fid (ms), cls (decimal), ttfb (ms), tti (ms), pageLoadTime (ms)}; PageSpeedAlert {id, triggerCondition, threshold, status (‘armed’|‘firing’|‘resolved’), lastFiredAt}. No migration.

API

• POST /api/analytics/page-speed
• GET /api/analytics/page-speed
• POST /api/analytics/page-speed/alerts

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Performance dashboard: show LCP, FID, CLS sparklines and trend. Top slow pages: list of 10 slowest URLs. Performance budget: set thresholds, view alert history. Export: download metrics as CSV/JSON.

The seam — why this is core

Core owns: speed metric collection, dashboard, honest reporting. Paid owns: advanced optimization recommendations, third-party integrations.

Core owns the interface + honest speed monitor; performance tracking is infrastructure, not a per-country obligation or credential.

Dependencies

• Storefront (must be able to post metrics)
• Settings system (alert thresholds)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Storefront posts metric {pageUrl: ‘/products/123’, lcp: 2000, cls: 0.05}; metric is stored in PageSpeedMetric
• Metric aggregation: averaging 10 metrics with lcp=[1500, 2000, 2500, …] produces avgLcp=2000
• Alert triggers if lcp > 2500 (performance budget); alert status changes to ‘firing’
• Admin views dashboard and sees ‘LCP 2.5s, FID 150ms, CLS 0.08’ with historical trend
• Export endpoint returns JSON with all metrics from past 7 days

Risks

Spam metrics: bots post fake metrics, inflating averages; mitigation: rate-limit POST endpoint, require storefront signing. Incomplete data: only 5% of page views post metrics (browser support, ad blockers); mitigation: document this limitation; metric is sample-based.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.