Multi-Tenant Commerce Platform — Systems Architecture · Designed, Not Shipped
The complete end-to-end architecture, specification, and 14-phase build plan for a custom multi-tenant storefront platform — branded partner storefronts, in-house subscriptions, a commission ledger, payouts, and tax. Designed end-to-end; leadership licensed a vendor before build began. A study in how I architect a system from scratch.
What the business needed
A US health-and-wellness company needed a custom e-commerce platform where every partner gets their own branded storefront on their own subdomain — with subscriptions, automatic partner payouts, tax, and fulfillment owned in-house rather than rented from a SaaS platform or stitched together from plugins.
The technical challenge
This is a systems-design problem, not a website. Multi-tenancy (wildcard subdomains, per-tenant branding, strict tenant isolation), money handled to the exact cent (commission economics, payouts, refunds, clawbacks), subscription billing on a custom schedule, PCI-compliant payments where card data never touches the server, and a schema designed so future markets, currencies, and languages become additive config — never a destructive migration on live data.
How I architected it
A full architecture designed before a line of code. Wildcard-subdomain tenant resolution with reserved-name protection and cached lookups, propagating each partner’s theme and logo across catalog, cart, checkout, and account. A commission engine that computes in integer cents (never floats), snapshots plan rates at order time so historical payouts never drift, and commits inside the order transaction so commission rows land with the order or not at all. Monthly payout aggregation with idempotency keys, a mandatory owner-approval gate, webhook reconciliation, refund clawbacks, and automated 1099 generation. A deliberate choice of a tokenized card vault plus a custom subscription scheduler — over the gateway’s native recurring billing — to support arbitrary cadences, pause-without-losing-continuity, and smart dunning. Tokenized checkout so card numbers never reach the server, keeping the business in the lightest PCI compliance scope. And a forward-compatible schema where every multi-market and multi-currency primitive ships at launch.
- Integer-cent commission ledger — money tracked to the exact penny, snapshotted at order time
- Custom subscription scheduler over card-vault tokenization (arbitrary cadences, smart dunning)
- PCI SAQ A: card data never touches the server
- Schema designed so new markets and currencies are additive config, never a destructive migration
Where it landed
Leadership chose to license an existing third-party product before development began, so the platform was never built — and the write-up is honest about that. What stands is the complete blueprint: every screen, data model, payment flow, and security control, designed and documented in full. Even unbuilt, it is the clearest demonstration of how I approach a complex system — design the whole thing first, so the build is predictable, secure, and doesn’t fall over the first time real money and real customers hit it.
Have a system like this to build?
If you need a platform, a custom integration, or a system where the logic matters — not just the pixels — let's talk about it.