docs: add platform market research and weighted integration priority ranking

Research to inform which mock platform (Amazon, Shopify, etc.) is worth
turning into a real integration next, after Etsy. Adds GMV/seller-count
market-size data for every platform in domains/accounts/platform.go, a
weighted scoring model (GMV 45%, API/inventory-webhook completeness 30%,
growth 15%, integration cost 10%), and the resulting ranked order.

Also fills in Etsy's own row, sourced directly from
domains/platforms/etsy/generated_client rather than external docs since
it's the one platform actually live in this repo: Etsy Open API v3 has no
webhook/push mechanism at all, and only the OAuth connection flow is
built so far - polling-based order/inventory sync doesn't exist yet. Etsy
is included as a reference score (3.85/10) against the same rubric used
for the unbuilt platforms, mainly as a sanity check on the model rather
than a claim that building it first was wrong.

Flags that the existing capability table's BigCommerce row doesn't match
an actual platform in this codebase (Tiktok does, and is now researched
instead), and that Tiktok Shop's API details are unconfirmed pending a
dedicated research pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-20 16:23:47 -06:00
co-authored by Claude Sonnet 5
parent ede7555d43
commit 308f16f6cc
2 changed files with 235 additions and 0 deletions
+72
View File
@@ -7,6 +7,78 @@ Wix, WooCommerce, Zoho) exists only as a **mock simulation layer** used for
development, demos, and testing the sync/reporting logic without needing
real store credentials. See `README.md` for the product-level roadmap.
## Platform integration priority
When picking the next mock platform to turn into a real integration (after
Etsy), use this weighted ranking of the 12 not-yet-live mock platforms. It
scores each on GMV/market opportunity (45%), API/inventory-sync completeness
(30%), growth trajectory (15%), and integration cost (10%) - see
`STORE_API_RESEARCH.md`'s "Weighted priority ranking" section for the full
scoring table, per-criterion reasoning, and the market-size/API research
it's built on.
1. **Shopify** (9.15/10) - cleanest/most complete API (webhooks for both
order and inventory events, modern GraphQL), still-strong GMV growth
(+29-35% YoY), and a proven self-serve distribution channel (the Shopify
App Store, where inventory-sync apps are an established category) that
no other platform here has an equivalent of.
2. **Amazon** (8.85/10) - largest raw dollar opportunity (~$575B in 2025
third-party GMV), and inventory-sync pain (suppressed listings, FBA
stranded-inventory fees) is one of the sharpest problems this tool could
solve there. `domains/amazon` already has the most real infrastructure
of any mock platform (the `ProcessEvents` LISTEN/NOTIFY loop, SSE
wiring), so a real SP-API integration reuses that instead of starting
from zero. Scores lower than Shopify mainly because SP-API auth (LWA +
AWS SigV4) and rate limiting are the most complex of any platform here,
and seller growth has gone flat.
3. **Tiktok Shop** (7.15/10) - hypergrowth (global GMV nearly doubled in
2025, projected to double again in 2026) is what earns it this spot, but
its API details are the least confirmed of anything researched -
`partner.tiktokshop.com` didn't yield readable docs during this pass.
Needs a dedicated research pass to confirm exact webhook/endpoint names
before treating this ranking as actionable.
4. **Walmart Marketplace** (6.35/10) - smaller in absolute GMV than the top
three, but growing ~50% YoY and a natural second-marketplace target for
sellers already on Amazon; full order+inventory webhook coverage.
5. **Wix** (6.35/10) - tied with Walmart on score but behind it on the
growth tiebreaker; full inventory-webhook coverage and an easy API, just
a smaller/less certain GMV number.
6. **WooCommerce** (5.95/10) - large store count (~4-6M) but no
platform-wide GMV figure exists (self-hosted plugin, no central ledger),
and no dedicated inventory webhook (relies on a `product.updated` proxy).
7. **Square Online** (5.90/10) - full inventory-webhook coverage and
well-documented APIs (shared with the rest of Square's product line),
but its ecommerce-specific GMV can't be isolated from Square's much
larger in-person POS business.
8. **Ebay** (5.75/10) - most sellers of any platform here (18.3M) but the
lowest GMV-per-seller by far, plus no dedicated inventory-change webhook.
9. **Squarespace** (4.75/10) - smaller GMV, no inventory webhook.
10. **Zoho** (3.85/10) - tiny confirmed store count (~2,196 globally).
11. **Ecwid** (3.20/10) - shrinking (-20% YoY store count).
12. **Big Cartel** (1.50/10) - last, and not close: no inventory API or
webhook at all is a structural dealbreaker for this tool's core use
case, independent of its (also declining, -41% YoY) market size.
(BigCommerce, which appears in the API-capability table in
`STORE_API_RESEARCH.md`, is excluded here - it isn't one of this codebase's
actual mock platforms; that table predates the platform list settling on
Tiktok instead.)
Etsy isn't in the ranking above (it's already built), but scores 3.85/10 as
a reference point if run through the same rubric - mid-pack-and-declining
GMV, and the *only* platform researched with zero webhook/push support of
any kind (order or inventory - confirmed directly against
`domains/platforms/etsy/generated_client`, not external docs). That's not a
retroactive case against having built Etsy - it was presumably chosen for
reasons this rubric doesn't score (an existing relationship, an easier path
to developer credentials) - but it's a reminder that the lack of any
webhook system makes real order/inventory sync a polling loop, which is
exactly the kind of integration cost this rubric undercounts once a
platform is more than superficially wired up. Note also that the OAuth
connection flow is the only part of Etsy that's actually built so far
(`domains/platforms/etsy/etsy.go`) - polling-based receipt/inventory sync
against the live API doesn't exist yet.
## Setup
1. Postgres running locally, with an `app_client` role/database matching