Shopify CRO Audit Pipeline

What it does

• Submit a URLThrough a branded form; choose whether to build extra business-context, and whether to deliver the report to Drive.
• Capture desktop + mobileIn parallel via headless Playwright — full-page screenshots, viewport-only hero shots, rendered HTML, and Lighthouse + CrUX metrics from PageSpeed Insights.
• Detect business contextCheap Gemini Flash-Lite call — industry, persona, business model, value prop, primary conversion goal.
• Analyse against six pillarsSufficient Product Info & USPs, Trust Building, Efficiency & Discovery, Checkout Optimization, AOV & LTV, and Urgency. Six parallel Gemini Pro specialists, synthesised into a unified findings list with per-pillar scores, per-section scores, and an ICE-ranked experiment backlog.
• Render a branded 17-slide deckVia python-pptx — cover, executive summary, business context, six-pillar overview, section scorecard, captures, per-section walkthroughs (Homepage / PDP / Cart / Trust / Mobile / Email / Performance with CWV tiles), priority table, 30-day action plan, closing.
• DeliverPPTX to a shared Google Drive folder via OAuth, with a download endpoint as fallback.
• Live audit detail pageFive-stage subway-rail visualization, ticking elapsed counter, cancel-with-confirm during the cancellable phases, status-aware hero (live / completed / cancelled / failed).
• Per-user ledgerMulti-tenant audit history with ownership-enforced routes; users only see their own audits and can never address another user’s by ID.

Tech stack

Engineering highlights

• H.01

  Pluggable LLM provider abstraction

  Same LLMClient Protocol drives Gemini and Claude implementations; swap providers per-audit via env var without touching the runner. Schemas are defined once and reused across providers so outputs stay comparable.

• H.02

  Six-pillar parallel analysis

  Specialist calls fan out via asyncio.gather(..., return_exceptions=True) so a single specialist failing doesn’t kill the audit; synthesis works with whatever returned. No agent framework — asyncio.gather is the right shape for stateless fan-out, framework overhead bought nothing.

• H.03

  Subprocess Playwright capture

  Capture runs in a child Python process (asyncio.run + Proactor on Windows) so the parent uvicorn — which inherits Selector — never has to deal with subprocess spawn. Sidesteps the NotImplementedError cliff entirely.

• H.04

  Cooperative cancellation

  Cancel endpoint flips audit status; the runner polls between every step, refusing to advance. Cancellation is a first-class status (cancelled, distinct from failed) with its own finding-step state and UI treatment. Cancel is also gated by phase — disabled once the runner enters the final 5s report + deliver window where nothing useful can be saved.

• H.05

  Single-process pipeline

  No Celery, no Redis, no external worker — audits run as asyncio.create_task from the POST handler, gated by an in-process asyncio.Semaphore (default 2 concurrent). Stranded audits from a server restart get reset on lifespan startup.

• H.06

  17-slide branded PPTX template

  Pure python-pptx, no Node subprocess. Variable display font bundled in-tree; logo + icon brand assets embedded directly; pinwheel-style mark drawn programmatically when a reverse-tone variant is needed; CWV thresholds encoded for the Performance slide; ISSUE / WIN / OPPORTUNITY badges consistent with the kind classification on every finding.

• H.07

  Audit detail = operational instrument

  Vertical subway-rail pipeline visualization with one node per stage; current stage gets an indeterminate orange progress bead; LIVE pulse + ticking elapsed counter; status-aware hero swaps between Live / Complete / Cancelled / Failed so the page’s center of gravity matches the moment.

• H.08

  API health by exception

  Polls /health every 30s; renders nothing while online or first-checking, surfaces only when degraded (slow response) or offline. Avoids "all green dot" noise; alerts only when there’s something to alert about.

What it demonstrates

• Productizing AI — turning an open-ended LLM capability into a fixed template + repeatable methodology + branded deliverable that can be sold for a fixed fee with a 24-hour SLA. The methodology is encoded as prompt structure, not a marketing slogan.
• Multi-provider LLM integration. Provider abstraction lets the operator swap Gemini for Claude in a single env var without touching any business logic — useful when one provider rate-limits, costs spike, or quality regresses on a specific audit type.
• Long-running async work in a single process. Fan-out + fan-in across six concurrent multimodal LLM calls, integrated with browser automation, file generation, and a third-party upload — without introducing a queue, broker, or worker pool until the math actually demands one.
• Brand system as code. A consistent visual identity expressed across two surfaces (PPTX + React) from one set of tokens + assets, enforced in code (report.py constants + index.css @theme block + DESIGN.md spec). Brand changes propagate via one commit.
• Cross-platform Windows-first dev experience. Subprocess capture, event-loop policy guards, font bundling for both runtime + viewer, Device Guard-aware npm scripts.