Skip to content

Business Context

Load this when you need to understand what the product is before making a change. For per-area depth, follow the routing table in the root CLAUDE.md instead.

Product

PaperRun is a postcard marketing automation platform for e-commerce. Brands use it to send physical mail tied to e-commerce signals (cart abandonment, win-back, post-purchase, loyalty milestones, etc.) and to attribute downstream orders back to those mailings.

Core workflow

  1. Campaign creation — A brand sets up a campaign (audience, template, send rules, schedule).
  2. Recipient targeting — Recipients are pulled from Klaviyo segments / Shopify / direct uploads, deduped, blocked-list filtered, and address-enriched.
  3. Image personalization — Front/back images are generated per recipient via Pixelixe, stored on Cloudflare Images.
  4. Print & mail — Mailpieces are dispatched to a printer provider (LOB, IntelliPrint, Stannp, Taylor) based on geography and template size.
  5. Order attribution — Orders synced from Shopify are matched back to mailpieces via email, address, discount code, and holdout-group analysis.

Attribution methods

  • Email match — order email == recipient email.
  • Physical address match — normalized shipping address matches a recipient's address.
  • Discount code — order used a discount code generated for the campaign.
  • Holdout group — control group recipients were intentionally not mailed; lift is computed against them.

For the full matching hierarchy, edge cases, and tie-breaking, see docs/attribution_methodology.md.

External integrations

  • Klaviyo — customer data platform (segments, profile properties, events).
  • Shopify — e-commerce source of truth (orders, customers, discounts, App Store install path).
  • Stripe — billing and metered usage.
  • Printer providers — LOB, IntelliPrint, Stannp, Taylor. Selected per mailpiece by geography / template size.
  • Pixelixe — image personalization.
  • Cloudflare Images — image storage and on-the-fly resizing.
  • Slack — internal tooling: slash commands for organization management, audit reports, alerts.
  • Linear — issue tracking. PR titles use [ENG-NNNN] prefix.

For an integration-by-integration overview see docs/architecture/integrations.md. For the integration client code layout see app/core/integrations/CLAUDE.md.