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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user