← Dashboard/Help & Docs
support@mavrtr.com

Getting Started

How the Mavrtr Engine Works

A transparent look at the 5-stage pipeline that turns a store URL into a research report.

When you click Run Research, the Mavrtr engine kicks off a 5-stage async pipeline. Each stage runs sequentially — the output of one feeds the next.

Stage 1 — Catalogue

The engine fetches the store's public Shopify product catalogue using the storefront API. It pulls product titles, types, descriptions, prices, and handles — enough to understand what the brand sells and where your focus product sits.

If the store is not on Shopify, this stage fails and the report cannot proceed.

Stage 2 — Research

This is the heaviest stage. A specialised research agent is given either a product brief or a brand brief (depending on your research mode) and instructed to hunt primary sources in this order:

  1. The brand's own reviews (Trustpilot, on-page reviews, Yotpo, ProductReview)
  2. Relevant subreddits and forums for the product's niche
  3. Amazon reviews of close substitute products
  4. Social media comments on competitor ads
  5. 2-3 direct competitor review pages

The agent synthesises all of this into structured signals: review signals, Reddit signals, competitor signals, and objection signals — all sourced from URLs it actually visited during that run.

Research is cached per store + product + mode for up to 7 days. Re-running a report with the same settings within that window uses the cached research, which is faster. Different modes (product vs brand) never share a cache entry.

Stage 3 — Customer Intelligence

The research output is fed to a customer intelligence analyst prompt. It produces 2-3 distinct customer avatars — each one describing a different type of buyer. For each avatar you get:

  • Demographic + psychographic snapshot
  • Pain points ranked by severity (1-10)
  • Desires ranked by intensity (1-10)
  • Objections with sharp one-liner rebuttals and recommended placement surfaces
  • Verbatim quotes pulled from the research
  • Awareness stage (Schwartz's 5 levels)
  • Dream outcome

Stage 4 — Strategy

A senior media buyer prompt takes the customer intelligence and generates a full campaign strategy:

  • Positioning statement
  • What's already working / key risks
  • 5 ad angles, each with a hook (≤14 words), primary text, CTA, target avatar, confidence score (1-10), and rationale
  • A CBO campaign structure with 3-5 ad sets, budget shares, audience descriptions, and placement recommendations

Stage 5 — PDF Generation

The report data is rendered into a branded HTML template using Jinja2 and converted to PDF with WeasyPrint. The PDF is uploaded to secure cloud storage and a signed download link is generated. You get a notification once it's ready.

What happens if a stage fails?

If any stage encounters an unrecoverable error, the report is marked as Failed with an error message. Common causes:

  • The store is not on Shopify (Stage 1)
  • The store has a very small catalogue or is heavily JS-gated (Stage 1)
  • Research timed out due to an unusually obscure niche (Stage 2)
  • The LLM returned malformed XML after the maximum retry attempts (Stage 3 or 4)

Failed reports do not consume a report credit.