7-Stage Website Audit Engine & pdfscript
7-stage Puppeteer, Lighthouse, axe-core, and AI-vision inspection pipeline compiling any live URL into a 14-page executive proposal PDF in minutes.
01 — The Operational Problem & Stakes
Agency sales teams and technical consultants spend hours manually running Lighthouse, checking mobile responsiveness, hunting broken security headers, taking screenshots, and formatting slide decks before pitching a prospect — or worse, they send generic text pitches with zero proof.
Hamid needed an autonomous engineering instrument that inspects a target company’s live website with real browser measurements and outputs an undeniable, boardroom-ready diagnostic document.
02 — System Architecture & Execution
The Website Audit Engine & `pdfscript` orchestrates a 7-stage headless Chromium pipeline: (1) DOM & network reachability capture, (2) Lighthouse Core Web Vitals (`LCP`, `CLS`, `INP`, `TTFB`), (3) `axe-core` WCAG accessibility tree audit, (4) HTTP security header & TLS posture inspection, (5) Technical SEO, canonical, schema, and locale tag analysis, (6) multi-viewport screenshot capture + AI vision UI critique, and (7) deterministic HTML/CSS print compilation into a 14-page branded PDF.
Hardened error handling ensures missing upstream network telemetry never crashes deep PDF page generation (verified across 83/83 pipeline tests and visual PDF page audits).
03 — Interactive Subsystem Topology (Click Any Node)
Headless Chromium & Lighthouse
Captures desktop and mobile viewports, measuring real LCP/CLS/TBT metrics and horizontal overflow offenders.
04 — Key Engineering Decisions & Trade-Offs
Real DOM Measurements Over Hallucinated Advice
Every finding in the 14-page PDF traces back to a measured Lighthouse metric, HTTP header, or axe-core selector — zero generic filler paragraphs.
Defensive Null-Safe PDF Pagination
Target sites frequently block trackers or time out sub-resources; hardening page-6 network waterfall templates eliminated crashes when `lighthouse.network` is partial.
Inter-Process File Locking for Concurrent Runs
Added deterministic file and account locks so batch audit queues never overwrite assets or double-dispatch reports.
Bridging Engineering Diagnostics to Executive ROI
Translates raw technical debt (`CLS 0.42`, missing `hreflang`, slow mobile LCP) into clear commercial impact for non-technical founders.
05 — Verified Build, Test & Runtime Proof
$ pytest tests/test_audit_pdf_pipeline.py
✓ 83/83 tests passed (including partial lighthouse.network fallback & brand metadata stamp)
✓ Output artifact: 14-page A4 Proposal PDF (annotated desktop + mobile captures embedded)
✓ Visual page-break check: 0 clipped tables · 0 orphan headings