E-commercecomplex complexity

Two-Sided Marketplace Architecture

Two-sided marketplace architecture with listings, transactions, trust systems, and dispute resolution that scales without losing supply or demand.

Components

Considerations

Alternatives

complex

Complexity

Fit

When this blueprint fits

And when to walk away from it

When to use this

You are building a platform where independent sellers list to independent buyers and you take a fee on transactions. The supply and demand sides have different needs and your architecture has to serve both without compromise.

When NOT to use this

If you only sell first-party inventory, you have an e-commerce store. The marketplace primitives (seller onboarding, payouts, dispute resolution) add real complexity that is wasted if there is no second side.

Architecture

System components

Key building blocks of this architecture, layered from infrastructure up.

Listing Management

Multi-category listings with attributes, media, draft states, and seller-controlled visibility. The data model has to flex to wildly different categories (a car listing has nothing in common with a freelance gig). I use a base listing entity with a flexible attributes table and per-category validation schemas.

PostgreSQLJSON SchemaMedia PipelineSearch Index

Search and Discovery

Faceted search with relevance ranking, geo filtering, and personalised recommendations. Marketplaces live or die on discovery. Invest in synonyms, query understanding, and zero-result rescue. Logged-out users get a different ranking than logged-in users.

ElasticsearchAlgoliaML RankingPersonalization

Transaction System

Escrow-based transactions with payment splits, holds, and refund flows. Built on Stripe Connect in most builds because rolling your own money movement is regulatory pain. The state machine is the heart of the system: every dispute, refund, or chargeback is a state transition with audit history.

Stripe ConnectXStateEscrowWebhooks

Trust and Safety

User verification, reviews, fraud detection, and content moderation. Trust is the marketplace product. New sellers need easy onboarding, established sellers need protection from scams, and buyers need recourse when things go wrong. See the fraud detection blueprint.

VeriffPersonaML FraudReview System

Messaging

In-app messaging between buyers and sellers with attachment support, automated moderation, and transcript retention for disputes. Same primitives as the real-time chat blueprint, with extra hooks for marketplace context like associated listings.

WebSocketPushModerationTranscripts

Payout Engine

Seller balances, scheduled payouts, tax document generation, and country-specific compliance. Marketplaces become unintentional fintech the moment they go international. I lean on Stripe Connect Express or Custom for the heavy lifting and own only the balance ledger.

Stripe ConnectLedgerTax APIs1099/W-9

Dispute Resolution

Workflow for buyer claims, seller responses, evidence collection, and admin decisions. Dispute resolution is a product, not a feature. Treat it like a small internal CRM with structured outcomes that feed back into trust scoring.

Internal ToolsState MachineAudit Log

Planning

Critical considerations

The things I have learned the hard way and would not skip on the next build.

Payment splits and escrow are complex. Use Stripe Connect or Adyen MarketPay rather than building money movement yourself unless your volume and team justify the regulatory burden.

Trust systems are the moat. Invest in verification, reviews, and reputation from day one. A marketplace without trust is a forum.

Plan for abuse and fraud from day one. Every successful marketplace attracts professional scammers within months. Rate limits, device fingerprinting, and human-in-the-loop review on high-risk actions are the baseline.

Liquidity matters more than features. Solve the chicken-and-egg problem in your launch market before building the next feature. Geographic concentration, category focus, and supplier subsidies all work.

Need a marketplace partner? Start a project.

Options

Alternative approaches

Where I would consider a different shape entirely, with the trade-offs spelled out.

Alternative 01

Sharetribe for rapid marketplace launch with managed infrastructure. The right call when the priority is validating supply and demand.

Alternative 02

Medusa for commerce-focused marketplaces when you want headless control with a familiar commerce model.

Alternative 03

Mirakl for enterprise marketplace operations on top of an existing e-commerce platform.

Alternative 04

Custom build for unique marketplace models (services, rentals, regulated industries) that do not fit off-the-shelf primitives.

Implementation

Related playbooks

Step-by-step guides for the harder parts of this architecture.

Designing Event-Driven Systems

Event-driven architectures unlock real autonomy between services, and they expose a whole new category of bugs if you do not respect their constraints. This playbook is the design discipline I use: model events as facts, version schemas carefully, choose the right broker, build idempotent consumers, handle ordering and failure, and add the observability that makes async systems debuggable in production.

Read playbook

Securing Your API Endpoints

API security is not a sprinkle of middleware, it is a layered set of defenses where any one missing layer opens the door. This is my full checklist for hardening API endpoints: authentication, rate limiting, validation, CORS, audit logging, and the response headers that mitigate the long tail of browser-side attacks. Used on every production API I have shipped.

Read playbook

In practice

Related case studies

Where I have applied this blueprint to real builds and what changed in practice.

Marketplace Trust and Safety Platform

A real-time trust-and-safety platform for a high-volume marketplace, blending rules, ML scoring, and human review into one decisioning system.

View case study

Thinking

Related insights

Essays where I argue the trade-offs behind the choices in this blueprint.

Complexity Is the Enemy

A meditation on complexity, simplicity, and why the most impactful engineering often involves removing things rather than adding them.

Read essay

Need a partner on this?

Need help implementing this blueprint?

I help teams adapt blueprints like this to their specific requirements and ship from planning through production.

Start a project Get in touch

Next up

SaaS Platforms | simple complexity

Internal Tools Architecture

Architecture for building internal tools and admin dashboards with rapid development, strong access control, and audit trails that satisfy compliance.

E-commerce