# Product-page cross-merchant match / price comparison (DESIGN)

**Status:** v1 BUILT for arpartsfinder 2026-07-03 (live-query, on /p/ pages).
**Applies to:** arpartsfinder (parts) shipped; onlineammofinder = follow-up.

## v1 as built (arpartsfinder, 2026-07-03)

`ngsite/product_match.py` (pure, unit-tested) + `queries.same_type_pool` (TTL-
cached pool) + the /p/ view + a "Compare prices" panel in product.html (two
tiers, per-row "$X less/more" delta, View jump link, reciprocal /p/ link).
SAFE_TYPES = {bcg, ch, trigger, muzzle}. The matcher gained dimensions during
tuning against real data: BRAND anchor (different brand => reject), CALIBER +
PLATFORM (AR10 vs AR15) as hard discriminators, MODEL-number match, and
masquerade guards so thread pitch (1/2x28), platform (AR10/SR25), and caliber
never get read as distinctive model codes. Validated: Radian Raptor-LT surfaces
6 merchants at ~$79.9x (confident); Breek-vs-Radian / AR10-vs-AR15 / 9mm-vs-5.56
correctly rejected. 9 unit tests lock the rejects. Tunables: `_CONFIDENT`/
`_POSSIBLE` thresholds, `_BRANDS` (static for v1 -> derive from scanner
brand_prefix later).

### onlineammofinder — FOLLOW-UP (NOT ported)
Ammo needs its OWN matcher tuning, not a copy: ammo `type` IS the caliber, so the
same-type prefilter already groups by caliber; discriminators are BRAND (Federal/
Hornady/Winchester/CCI/PMC/Blazer/...), GRAIN, bullet type, and ROUND COUNT — and
there's no AR-platform concept. Ammo may actually match BETTER (more structured),
but it must be built + validated against ammo data separately. Until then ammo's
product.py is untouched (feature simply absent there).

## The idea

On a `/p/<id>` product page, show a small "also available from" / price-
comparison panel: OTHER merchants that carry the SAME physical product, with
their price, so the product page becomes a mini comparison instead of a single-
merchant listing. (Longer term this is what makes each `/p/` page genuinely
unique + rankable — see the SEO discussion re thin vs rich product pages.)

## Key reframe (the unlock)

We are NOT searching external sites. **We already have every merchant's listing
in our own `parts` table** (that's the whole site). So this is a within-catalog
"find the same product across `company` values" problem — a DB query + a good
same-product matcher, computed over data we already hold.

Sanity: 15 distinct companies carry in-stock BCGs today, so real overlap exists.

## What we have to match on (2026-07-03)

`parts` columns: `id, type, company, description, price, url, img, added,
removed, instock, hidden, last_seen`. So: **`type`** (our category), **`description`**
(the title — the ONLY text signal), **`company`** (merchant), **`price`**.
NO SKU/UPC, NO manufacturer field, NO structured attributes yet (no attrs/group
tables). => it is fundamentally **title-driven fuzzy matching within a type.**
We DO already know the manufacturer brands (15 retailers carry a `brand_prefix`
in their scanner config = a brand vocabulary).

## The matcher (precision-first, layered)

1. **Hard prefilter:** same `type`, different `company`, `instock=1`. Cheap;
   kills most false positives (a BCG only competes with BCGs). Pool ~hundreds.
2. **Normalize the title:** lowercase, strip punctuation, normalize obvious
   abbreviations (bcg <-> bolt carrier group, milspec). **Neutralize brand
   tokens** using the brand vocabulary (brand_prefix values + company names) —
   fixes the "we prepend brand for manufacturer-direct sellers, others don't"
   asymmetry (strip brand from both sides, or score it as its own field; a
   missing brand word must not tank the match).
3. **Order-independent similarity:** RapidFuzz `token_set_ratio` (compare the SET
   of words) so transposed / reworded titles and extra/missing words still match
   ("extended latch charging handle" ~= "charging handle w/ extended latch").
4. **Model-number extraction (highest-precision signal):** pull distinctive
   alphanumeric codes (DDM4V7, ACI-15, Mk4, part numbers) from the title. A
   SHARED model number is near-unique. Rule of thumb: a small token overlap is
   trustworthy IF it's a model number, dangerous if it's generic ("barrel").
5. **Composite score -> tiers:** token_set + brand-match + shared-model-number
   (+ price sanity as a soft tiebreak, NEVER a filter — price varying is the
   point). Two DISPLAYED tiers (Mike's call): **Confident match** and
   **Possible match** (both shown, clearly labeled). Below threshold = not shown;
   clean "no confident matches" empty state, never pad with weak guesses.

## Guiding principle

A WRONG match is far worse than a missing one — showing "same part, $40 cheaper
at X" when it's a DIFFERENT part erodes trust and can send someone to buy the
wrong thing. Bias hard to precision. Missing a merchant is a shrug.

## The variant hard-case (why launch order matters)

A 16" barrel is NOT the same product as the 18" barrel of the same model (same
model number, different item — an 18" isn't "more expensive," it's different).
Disambiguating variants needs attributes we DON'T have yet (length, caliber,
weight). So:
- **Launch first on LOW-VARIANT types** where the title fully identifies the
  item: BCGs, charging handles, triggers, muzzle devices. Title matching is
  reliable there. (Ammo analog: caliber + grain + round-count are already
  strong, mostly-structured discriminators — ammo may match BETTER than parts.)
- **Hold variant-heavy types** (barrels, complete uppers) until length/caliber
  attribute extraction exists — else we'd confidently show wrong "cheaper"
  matches (the trust-killer above).

## Build shape (decided)

- **v1 = live query, no new schema.** MySQL FULLTEXT on `description` within
  `type` to generate candidates, score the top ~30 in Python at render, cache
  the result per product (~mins TTL like /instock/popular). Prove the UX + the
  matcher quality on the low-variant types first.
- **Endgame = precomputed clusters.** A batch job assigns a `product_group` id;
  the page just reads its group. Slot **UPC/SKU** in as the GOLD key when the
  AvantLink feed enrichment lands (fuzzy matching becomes the fallback). Same
  composite-score tech as the retailer-migration auto-mapper; the destination of
  the cross-retailer-merge idea.

## Automation stance (decided)

**Fully automatic** — no routine human review. Per
[[feedback-minimize-site-maintenance-overhead]], maintenance must be minutes/week.
Achieve it via a high precision threshold (rare wrong matches). Once clusters
exist we can re-evaluate whether ANY supervised review is worth it; the bar is
"does it save more of Mike's time than it costs." v1 has NO review queue.

## Open / later

- Exact display: how many matches, sort (price asc?), how to show the two tiers.
- Kits/bundles vs bare item (a "BCG kit" is not a bare BCG).
- Reciprocal: link each match to its own `/p/` page (mutual discovery + internal
  linking = SEO win).
- Feeds this: [[feature-site-product-detail-share]], [[feature-cross-retailer-merge]]
  (if it exists), [[feature-avantlink-feed-enrichment]] (UPC gold key),
  [[feature-retailer-migration-auto-mapper]] (shared composite-score tech).
