Case study: marketplace
Сквозной кейс сайта в формате «я повторю, как понял задачу»: бизнес-описание маркетплейса своими словами, без архитектурных терминов. Этот текст затем прогоняется через скиллы методологии — из него получаются API, доменная модель и UseCase-ы.
This is the site's end-to-end example. I took a typical "let me repeat how I understood the task" conversation — the one that usually happens after the first meeting with a client, before you get down to estimation and architecture.
There isn't a single line here about databases, queues, or aggregates. There's only the business — described in the words the participants themselves use. This text is then handed to the methodology skills, which derive the technical artifacts from it: API contracts, the domain model, UseCases.
What this is all about
You are building a marketplace — a platform where some people sell their goods to other people. You yourself neither manufacture nor warehouse anything: your role is that of a guarantor intermediary.
Your sellers are varied: large stores with thousands of listings, and private individuals who sell a couple of items a month. Buyers are ordinary people. Between them stands your team: listing moderators, dispute operators, accounting, support.
You make money in two ways. The primary one — a commission on every confirmed sale. The secondary ones — paid promotion in search results, service fees for packaging and insurance.
Who uses the platform
The platform has three main "faces," and each needs its own interface.
The buyer comes to find and buy. What matters to them: price, availability, reviews, delivery speed. They most often log in via phone or a social network — nobody wants to remember passwords.
The seller comes to earn. What matters to them: adding a product quickly, seeing their orders, getting paid on time, resolving a dispute quickly if one arises. They log in with a corporate account — usually with two-factor protection.
The marketplace operator — these are your employees: moderators, dispute specialists, the finance department. They work from the inside, through corporate SSO with mandatory MFA. They have the broadest permissions, which is why every action is written to the audit log.
There are also couriers and pickup points — but they talk to the platform through their own APIs, not through interfaces. We treat them as external services.
What exists on the platform
To keep speaking the same language going forward, let me pin down how we name things.
Product — a specific item from a specific seller. The same iPhone from two different sellers is two different products, because they have different prices, stock, ratings, and each seller is responsible for their own. This is important: products don't "merge."
Product card — what the buyer sees on the storefront: photos, description, price, stock, reviews.
Cart — a temporary set of products. Until it turns into an order, nothing is reserved: the stock may go to another buyer.
Order — a financial document. Once an order is placed, the products are reserved, and the seller sees "a sale has landed on my plate."
Payment — an attempt to charge money. A single order may be paid over several attempts: the wrong card was entered, 3DS didn't go through, they tried again. An order becomes paid only after the bank has confirmed the charge.
Refund — a reverse movement of money when a product is returned. Not to be confused with cancellation: cancellation is possible before shipment, a refund — after receipt.
Dispute — this is when the buyer says "wrong item / defective / never arrived," and the seller disagrees. That's when an operator steps in and makes a decision.
Commission — your percentage of a confirmed sale. Seller payout — the amount you transfer to them once a week: sales minus commission minus refunds.
Promo code — a coupon giving a discount on the cart or on specific products.
How a purchase happens
Let me tell it as a story, step by step — that way it's clearer.
The buyer opens the site or the app. Searches for a product — via search or catalog. Opens a card, sees availability, price, seller, reviews. If it suits them — they add it to the cart.
In the cart, the buyer can enter a promo code and choose a delivery method (address or pickup point). The total is recalculated: products × quantity, minus discounts, plus delivery.
Then they click "Checkout." The system reserves the stock at each seller who ended up in the cart and takes the buyer to the payment form. For this operation we allow, say, 15 minutes — if payment doesn't arrive within that time, the reservation is released and the order is marked "expired."
Once the payment goes through — the order moves to the "paid" status. The seller gets a notification, packs the parcel, and hands it to the courier. The order becomes "shipped."
The courier delivers — the order becomes "delivered." If the buyer doesn't open a dispute over the next 14 days — the order is closed and the revenue is credited to the seller.
What happens when something goes wrong
Everyone writes the happy path. The difference is in how you handle problems.
The buyer changed their mind before shipment. For example, the order is paid, but the seller hasn't handed it to the courier yet. The buyer clicks "Cancel." The reservation is released, the money is refunded through the same payment gateway. Everything is simple here.
The buyer changed their mind, but the parcel is already on its way. Trickier — you either wait for the courier to bring the package back, or arrange for the buyer to return it to a pickup point themselves. The money is refunded only after the product has physically returned to the seller.
The buyer received it, but something is wrong. A defect, the wrong color, someone opened the box. The buyer opens a dispute, attaches photos and a description. The platform notifies the seller — they have three days to respond. If they agree — a refund is issued. If they refuse or stay silent — the dispute goes to an operator, who investigates and makes a decision. The decision is recorded in the system as part of the order's history — in case someone later wants to check it.
The payment gateway went down. The buyer entered the card, the bank doesn't respond for 30 seconds. We can't leave them hanging — we need a strategy: show "try again," freeze the order for a short time, check a minute later through the gateway's alternative channel. We'll come back to this when we get to resilience.
The money was already paid out to the seller, and the buyer opened a refund. The most painful case. The platform can't "recall" a payout that has already gone out — the money is deducted from the seller's internal balance, and in the next payout cycle they receive less. If the balance goes negative — the seller's orders are frozen pending investigation.
What the seller does
The seller has their own life on the platform.
Lists products. Creates a card, fills in the description, sets the price and stock, chooses a category. The card goes to moderation — an operator checks that there are no prohibited items and that the category is correct. If OK — the card appears in the catalog; if not — it comes back with a comment.
Processes orders. Sees in their dashboard "here are four new orders." Packs them, hands them to the courier, marks them in the system.
Receives payouts. Once a week the system gathers all their closed orders and calculates: sales minus your commission minus refunds minus penalties, if any. If the total exceeds the payout threshold (say, 1000 ₽) — the money goes to the seller's bank account. If it's less — the balance accumulates until the next week.
Sees reports. How much they sold, the average commission, which products were returned most often. This is useful both for the seller themselves and for offloading support — fewer "where's my money" questions.
What the marketplace operator does
Operators are your in-house team. They handle everything that can't be automated.
Moderators review new product cards. Dispute specialists resolve conflicts between buyers and sellers. The finance department reviews large payouts and decides what to do with blocked accounts. Support answers buyers and sellers on routine questions.
An operator has broad permissions, which is why every action of theirs is written to the audit log — who, when, on which order, what they changed. This is needed both for security and in case of investigations.
What's important to keep in mind
A few rules that sound obvious but determine half of the work.
- The order total = always the sum of line items minus discounts plus delivery. No "off-by-a-kopeck discrepancies," or accounting breaks.
- You can only reserve what's in stock. Negative stock doesn't exist — a reservation either succeeds or is denied.
- One promo code — one application in one order. They don't stack.
- The seller can't change the price of an order that's already placed. Buyer protection.
- After shipment, an order can't be "cancelled" with a single button — only a refund with a reverse movement of the product can be issued.
- A money refund is impossible once the money has been paid out to the seller — it's compensated from their internal balance.
- Only the buyer can open a dispute, and only within 14 days of receipt. Protection against abuse.
- The buyer sees only their own orders. The seller — only orders with their own products. The operator — all of them. No one sees anyone else's.
- A payment is considered successful only upon confirmation from the bank, not before. No "optimistic" confirmations.
What our volume targets are
To understand what we're building — a small startup or a national-scale platform — let me pin down the target numbers. These aren't what you have now, but what you're preparing for.
| What | How much |
|---|---|
| Active sellers | 200,000 — 500,000 |
| Product cards on the storefront | 50 — 100 million |
| Active buyers per month | 10 — 15 million |
| Orders on a normal day | around 500,000 |
| Orders on a peak day (Black Friday, 11.11) | up to 2 million |
| Search and catalog requests | up to 50,000 per second |
| Checkout requests | 200 — 500 per second |
| Connected payment gateways | 5 — 10 |
At numbers like these, "one server with one database" physically doesn't work — you'll have to distribute the load, build caches, use queues. That's already the engineering part, which we move on to in the following chapters.
What you want in terms of reliability and timelines
In conversations with a client this part is usually skipped, and that's a mistake — without it engineers can't estimate the cost.
Catalog and search must work "always" — because if they go down, there won't be a single sale. We aim for 99.95% availability, which means — no more than 4 hours of downtime per year.
Checkout is a bit easier — 99.9% (about 9 hours per year). If it's briefly down at night — that's survivable.
The seller dashboard — the most "tolerant" one — 99.5%. If it goes down for half an hour at lunchtime — sales continue, the seller will log in later.
Buyers' personal data (address, phone, full name) — stored encrypted, all access is logged to the audit, deleted on request or 5 years after the last order. These are the requirements of Russia's Federal Law 152-FZ.
Cards and accounts — not stored at all. Only tokens from the payment gateway, which is itself PCI DSS certified. This lifts a huge layer of work and risk off us.
What we don't do in the first version
To keep the launch realistic, we deliberately limit the scope.
- Russia only and rubles only. No international shipping, customs, or multi-currency.
- Only regular sellers and buyers. No sub-marketplaces, no B2B storefronts with price lists, no referral programs.
- Storage at the seller only. No platform warehouses, no FBO/FBM models.
- No in-house courier service. Only integrations with external logistics providers.
These are business simplifications, not technical ones. If you later want to add them — the essence of the processes and roles doesn't change, only the details get more complex. The architecture must allow this without a rewrite.
What's next
This text is how I understood your business. If something is described incorrectly — say so now, because everything else is built on this text: the API, the interfaces, the timelines, the budget.
Once we align our understanding, the engineering part begins:
- API contracts — what exactly the buyer, seller, and operator can call. The API design skills help here.
- What's inside — what services we'll have, what their areas of responsibility are, how they communicate. At this stage, aggregates, events, scenarios are derived from the business description, and from those — concrete UseCase + Handlers.
- Where it can fail — handling gateway errors, retries, idempotency; see resilience patterns and distributed patterns.
Artifacts for each service are published as separate case-study articles. How they relate to this business description is covered in the Use Case specification.