Lighthouse Audit Tool

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/lighthouse-audit-tool/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants need visibility into their site’s SEO, performance, and accessibility scores to compete with established players and prove site quality to stakeholders. This feature provides a built-in Lighthouse audit runner and historical tracking dashboard.

The problem

I don’t know my site’s performance, SEO, or accessibility scores. I can’t explain to investors or partners why our conversion rate is lower than competitors, or whether fixes actually improved the metrics.

What it does

• Run Lighthouse v14+ audits on-demand via admin dashboard for homepage and top landing pages
• Store audit results in audit_runs collection (timestamp, scores, opportunities, passing audits)
• Display scores (Performance, SEO, Accessibility, Best Practices, PWA) as percentages in real-time dashboard
• Show trend graphs (last 30 days) of each score category to identify improving or regressing metrics
• List top opportunities ranked by impact (e.g. ‘Unused JavaScript 45ms’, ‘Image sizing 20ms’)
• Export audit report as PDF for sharing with stakeholders
• Store up to 180 days of audit history; auto-purge older runs
• Show estimated mobile vs desktop score splits if audit runs on both

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.

• Continuous scheduled audits (e.g. daily automatic runs) — this is async job infra that should not block the first ship; can be a plugin extension later
• Real User Monitoring (RUM) — that requires injecting JS into customer storefronts, which is frontend instrumentation, not backend audit infrastructure
• Comparative scoring against competitors or industry benchmarks — this data does not exist in AstroBaaS and would require external APIs

Data model

audit_runs collection: {id, timestamp, url, device (mobile|desktop), performance, seo, accessibility, best_practices, pwa, opportunities: [{title, savings}], passing: [{title}]}. No migration required; new collection.

API

• POST /api/admin/audits/run — trigger audit on given URL
• GET /api/admin/audits — list recent audit runs with pagination
• GET /api/admin/audits/:id — fetch single audit result with full details
• DELETE /api/admin/audits/:id — delete audit run (for privacy/storage cleanup)

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

Admin

Admin panel shows ‘Audits’ section with Run Audit button, target URL selector (homepage, top pages), and result cards showing score bars (90+ green, 50-89 orange, <50 red). Clicking an audit shows drill-down: opportunities table (impact estimate), passing audits checklist, and exportable PDF. Trend graphs update as new runs are stored.

The seam — why this is core

Core owns audit UI and result storage; Lighthouse library (open-source, no credential needed) runs locally on merchant’s server, never in cloud. No paid seam — this is infrastructure visibility.

Core owns the interface + honest audit runner; quality metrics are infrastructure, not a support commitment or credential.

Dependencies

• Existing admin dashboard infrastructure
• page_view or analytics collection (to identify top pages, or merchant manually selects URLs)

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.

• Run Lighthouse audit on a test storefront URL and confirm audit_runs collection receives results with performance/seo/accessibility scores
• Verify audit results show at least 3 opportunities (e.g. unused JS, image sizing)
• Confirm trend graph renders for 10+ sequential audits on same URL without duplicating data
• Verify PDF export includes merchant name, URL, score card, and opportunity list
• Confirm old audits (>180 days) are purged without deleting recent runs
• Verify audit runs cannot be manually injected with invalid scores (scores must come from Lighthouse CLI)

Risks

Lighthouse CLI may hang on slow or unreachable URLs, blocking admin workflow. Implement timeout (10s) and queue audits async; never block admin on audit completion. Storing full opportunity JSON per audit can bloat audit_runs; design schema to index by score only, fetch opportunities on drill-down.

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.