Architecture, stack, key decisions and the quality gates DEV3 Shipdrop passed before release.
The engineering behind Shipdrop: a pure routing planner, stock held by journalled reservations, conditional state transitions and an append-only ledger, with the known edge cases written down.
The problem it solves
Dropshipping looks like a shop until an order has to be split. One paid order may need three suppliers, each with its own stock, minimums and shipping rates. Stock is shared by every store, so two shops can buy the last unit at the same moment. Suppliers reject, go silent or ship late, and the order must be rerouted without charging the customer twice or losing the money trail. The platform holds the cash, so every cent must be traceable to a merchant balance, a supplier payable, a fee or a payout, and a refund must say who bears the cost. Each of those steps can be retried or raced.
Architecture and approach
Shipdrop is a Next.js 16 application on MongoDB with a shared DEV3 core for auth, billing and tenancy. Stores are tenants: a Mongoose plugin scopes every query by an immutable organisation id and fails closed, cross-tenant code lives only in the platform folder and scripts, and a unit test greps for violations.
A pure routing planner
The planner takes a basket and the candidate sources and returns a plan: priority, cheapest or fastest, with a tolerance that prefers a supplier already on the order and supplier minimums that move a line or send the order to review. It is pure, so 24 routing vectors run in unit tests.
Stock is held before it moves
A reservation writes a journal row first, then updates the stock count and the hold in a single update. A crash is recoverable and a release is exactly-once. Feeds apply in sequence order and never touch reserved stock.
Conditional transitions
Every supplier order state change is a conditional update, so two racing calls produce one outcome. A reject or time-out sets a reroute-pending marker in the same update, a lease prevents two workers rerouting at once, and the hourly acknowledgement job repairs anything left pending.
An append-only ledger
Merchant postings carry a unique key per entry, which makes every retry safe. A ledger check compares each balance with the sum of its entries and prints the platform float. Refunds by fault decide whether the supplier order shrinks, the merchant bears the cost or the supplier earns a credit on its next statement.
Quality gates and results
Shipdrop 1.0.0 passed its seven checks on the final code: 238 app tests and 49 core tests, a 153-route production build with 208.0 KB gzipped first-load JavaScript and CSS on the home page, 176 routes and 18 happy paths in a headless browser, an install test from the packaged zip and a clean secret scan. The demo dataset holds 886 network products, 3,862 orders and 5,910 supplier orders.
Remaining edge cases are written down on the item page: a few rare race windows in refunds and rerouting, a draft whose stock re-reserve fails, and fees booked in the store currency.
Tech stack
| Area |
Technologies |
| Application |
Next.js 16 App Router, proxy.ts host routing, Server actions, React 19, TypeScript |
| Tenancy |
Mongoose tenant plugin, Immutable orgId, Fail-closed queries, Impersonation with audit |
| Dropshipping |
Pure routing planner, Journalled stock reservations, Feed sync, Margin guard, Supplier order pages |
| Money |
Append-only ledger, Retry-safe postings, Payouts and statements, Ledger check |
| Frontend |
Tailwind CSS 4, three.js route board, Theme presets |
| Quality |
Vitest unit suites, Routing vectors, Browser smoke script, Install-from-zip test |
Inside the build
Margin calculator — Pick a markup and see profit per unit after fees.
Dark mode — The same landing page on the ink theme.
