How to Build Template 3: Two-Sided Marketplace Platform

How to Build Template 3: Two-Sided Marketplace Platform

This template shows how to model a two-sided marketplace platform at the System Context level. It is intentionally generic so it can work for ride-sharing, delivery, home services, freelance platforms, or any other marketplace where supply and demand need to be matched in real time.

A two-sided marketplace is architecturally different from a standard web application because it must serve two user populations with fundamentally different incentive structures, different interaction patterns, and different trust requirements — simultaneously. The platform is not just a product; it is a coordination mechanism. Getting this visible in the architecture from the very first diagram is essential for building a shared understanding with stakeholders.

What This Template Shows

• Consumers and providers as separate primary actors with distinct roles, goals, and trust levels
• Internal marketplace operations roles that are often invisible in product diagrams but are critical to the platform's ongoing health
• The platform as the central coordination system — matching supply and demand, enforcing rules, handling money
• The external systems that enable payments, routing, real-time sync, trust and safety, identity, compliance, and analytics

This level is ideal when you want to explain the business and systems landscape before talking about specific containers. It answers the question "what is this system and who does it interact with" before "how is it built."

Embedded Diagram

Why This Context Diagram Works

The defining architectural property is the two-sided marketplace itself. The platform is not a store. It does not own the goods or services being sold. It coordinates between the people who supply them and the people who want them. That distinction — marketplace versus retailer — drives almost every architectural decision downstream.

A marketplace that matches riders to drivers is architecturally similar to one that matches buyers to handmade goods sellers or homeowners to plumbers. The matching problem, the payment split, the trust problem, the provider onboarding problem, and the supply-demand balancing problem are structurally the same.

The external systems also reveal architectural constraints that are not optional:

Marketplace payment flows are more complex than standard e-commerce payments. The platform typically handles a three-party transaction: consumer pays, platform takes a fee, provider receives the remainder. This requires payment infrastructure that supports split payments or marketplace payouts — Stripe Connect and Braintree are the dominant options. Standard payment processing alone is insufficient.

Real-time synchronization is a defining characteristic. When a consumer requests a service, providers need to see it immediately. When a provider accepts, the consumer needs to know immediately. When a provider's location changes, the consumer's map needs to update. This is not a polling problem — it requires persistent connections (WebSockets) or a real-time database push, which is why Firebase Realtime Database and Pusher appear as external dependencies.

Jurisdiction-specific compliance means the platform's architecture must change when it enters new markets. Driver background check requirements differ by country and sometimes by city. Payment regulations, tax reporting obligations, labor classification laws, and data residency requirements all vary by jurisdiction. A marketplace that plans to expand geographically needs to build compliance adaptability into its architecture from the start, which is why Regulatory Compliance APIs appear as a distinct external system.

Provider screening is not just a product feature — it is an architectural constraint. Marketplaces that allow unscreened providers create liability risk. Background checks, license verification, identity verification, and ongoing monitoring are all distinct processes that integrate with third-party screening providers. The architecture must show where providers enter the system and what they must pass through before they can transact.

Core Elements To Include

People

Consumer The demand side of the marketplace. Consumers discover available services or goods, request or purchase them, and rate their experience. From an architectural standpoint, the consumer experience is primarily about discovery, trust signals (ratings, reviews, verification badges), frictionless payment, and real-time feedback during service delivery. Consumer trust in the platform is driven by knowing that providers have been vetted and that payments are safe — both of which have architectural implications.

Driver / Courier / Service Provider The supply side. This population is what makes a marketplace work; without enough providers, consumers get poor service, they leave, and the marketplace collapses. Providers typically use a separate mobile application or interface optimized for their workflow: receiving job offers, navigating to locations, managing their availability status, and tracking their earnings. From an architectural standpoint, providers are a different threat model than consumers — they are authenticated business actors whose compliance with screening, licensing, and tax reporting requirements must be tracked.

Operations Manager Internal staff responsible for the health of the marketplace at the system level: monitoring supply-demand balance by region and time, managing pricing rules and surge logic, overseeing service quality metrics, and making policy decisions that affect both consumers and providers. Operations managers interact with internal dashboards and analytics tools. Their workflows depend heavily on the Analytics and Data Warehouse layer — they need real-time and historical views of the marketplace that the consumer and provider apps do not expose.

Support Agent Internal staff handling consumer and provider issues: disputed transactions, account problems, service quality complaints, and exception cases. Support agents need access to transaction history, user account data, provider screening status, and communication logs. They often need to take actions — issue refunds, temporarily suspend accounts, manually match or cancel bookings — that require elevated permissions not available to consumers or providers.

Trust and Safety Analyst Specialized internal staff focused on fraud, abuse, and policy violations. This role monitors for suspicious patterns — fake accounts, payment fraud, manipulation of ratings, collusion between consumers and providers — and investigates reports of serious incidents. Trust and safety is an ongoing operational function in large marketplaces, not just a launch checklist. The architecture must give these analysts access to data and tooling to do their work effectively.

Main System

Two-Sided Marketplace Platform The central system: orchestrates matching between consumers and providers, manages the transaction lifecycle from request to completion, handles the financial settlement, maintains the reputation system (ratings and reviews), and enforces the rules that protect both sides. The platform is the trust intermediary — both consumers and providers trust it to be a fair broker, which is why fraud, disputes, and trust and safety handling are owned by the platform rather than delegated to external systems.

External Systems

Stripe Connect / Braintree The financial infrastructure for marketplace transactions. Standard Stripe or Braintree processes payments in a two-party flow (customer pays merchant). Stripe Connect is purpose-built for platforms: it supports connected accounts for providers, split payments (platform fee deducted at charge time), and scheduled payouts to provider bank accounts. It also handles tax form generation (1099s in the US for providers above earnings thresholds), which is a compliance obligation in gig economy platforms. The choice of payment infrastructure is one of the most constrained architectural decisions in a marketplace — changing it later requires re-migrating all provider payment accounts.

Google Maps Platform / Mapbox Provides the geographic intelligence the marketplace depends on: displaying the map to consumers and providers, geocoding addresses entered by users, calculating routes and estimated travel times, estimating distances for pricing, and displaying real-time provider locations. For most marketplaces, maps are not just UI decoration — they are core to the product. Estimated arrival time accuracy directly affects consumer trust and booking conversion rates. Route optimization for multi-stop delivery affects provider earnings. The choice between Google Maps and Mapbox often comes down to pricing at scale, customization requirements, and offline capability needs.

Firebase Realtime Database / Pusher The real-time synchronization layer. When a consumer posts a request, providers within range need to see it within seconds. When a provider accepts, the consumer needs confirmation within seconds. When a provider is en route, the consumer's map needs to update every few seconds with the provider's location. None of this is achievable with standard HTTP polling without unacceptable server load. Firebase Realtime Database provides a client-synchronized data structure that pushes changes to all connected clients; Pusher provides a managed WebSocket layer for more custom real-time event patterns.

Twilio Handles all consumer-provider communications — typically anonymized phone calls and SMS messages during active service delivery. Anonymization is an important marketplace pattern: consumers and providers should not need to exchange personal contact information to coordinate. Twilio masks both parties' numbers through a proxy number for the duration of the booking. After completion, communication is routed through the platform's messaging system rather than direct contact, which maintains the platform's ability to monitor for policy violations and resolve disputes.

Background Check Provider / Checkr Manages provider screening during onboarding. Before a provider can take their first booking, the platform typically runs identity verification, criminal background checks, driving record checks (for platforms involving driving), and license verification. Checkr is the dominant US provider for gig economy background checks; other jurisdictions have their own equivalents. The screening result determines whether the provider is approved, approved with conditions, or rejected. Ongoing monitoring (continuous criminal background check subscriptions) is also a feature of mature trust and safety programs.

Auth0 / Firebase Auth Manages authentication for both consumers and providers. Marketplace platforms often have more complex identity requirements than standard web apps: consumers authenticate via social login or email; providers authenticate via email with additional identity verification; internal staff authenticate via SSO with the enterprise directory. Auth0 supports multiple authentication flows, organizations (for separating consumer and provider identity namespaces), and MFA policies that can differ by user type.

Regulatory Compliance APIs A catch-all for jurisdiction-specific compliance integrations: tax reporting APIs, local licensing verification services, labor classification monitoring tools, data residency requirements, and local payment regulations. In practice this is not a single external system — it is a category of integrations that grows as the marketplace expands geographically. Representing it as a single element in the context diagram signals to stakeholders that compliance is a recurring external dependency, not a one-time legal review.

Segment / Amplitude The analytics and data layer. Segment acts as a customer data pipeline — it captures user events from all client applications and routes them to downstream tools: data warehouses, marketing automation, A/B testing tools, and analytics platforms. Amplitude provides product analytics: funnel analysis, retention cohorts, feature usage, and experimentation results. For a marketplace, the most critical metrics are supply-demand balance, conversion rates by geography and time, provider utilization, and consumer lifetime value — all of which require a robust analytics pipeline.

The Matching Problem

The core function of the marketplace platform — matching consumers to providers — is architecturally distinct from other platform operations and deserves explicit attention.

Matching is typically the most technically demanding part of a marketplace system. It must happen in near real-time, under variable load, with conflicting constraints: minimize wait time for consumers, maximize earnings for providers, minimize empty travel, respect geographic constraints, handle surge and shortage conditions gracefully.

At the context diagram level, matching is not visible — it is internal to the platform. But when you zoom into the container level, the matching engine is usually a dedicated component with its own state store, its own optimization logic, and its own real-time communication channel to provider applications. Understanding that this component exists and that it drives many of the real-time infrastructure choices helps stakeholders understand why the platform is more technically complex than it might appear.

The Trust Deficit Problem

Every marketplace starts with a trust deficit. Consumers and providers do not know each other. The platform must substitute for the personal trust that would exist in a non-marketplace transaction.

The architecture reflects this: background checks before providers can transact, ratings after each transaction, anonymized communications to prevent off-platform transactions, dispute resolution processes, and trust and safety teams with the tools and data access to investigate issues. Each of these is an external system dependency or an internal capability that must be built.

Trust and safety is also an ongoing cost — not a feature you build once. As the marketplace grows, abuse patterns evolve, new fraud vectors emerge, and local regulations impose new verification requirements. The architecture should make it easy to add new screening integrations, new fraud detection signals, and new compliance workflows without re-architecting the core transaction flow.

How To Adapt It

To specialize this template for a specific marketplace type:

• Rename Consumer to Buyer, Passenger, Homeowner, or Client depending on the domain
• Rename Provider to Courier, Driver, Contractor, Freelancer, or Seller
• Keep the compliance and trust layer if provider onboarding involves any regulated activity or credential verification
• Keep the real-time synchronization if the service delivery is time-sensitive or location-dependent

If your system is not real-time — for example, a freelance marketplace where projects unfold over days rather than minutes — you can remove the real-time database dependency. The matching and communication patterns will be different, but the payment split, trust and safety, and analytics dependencies remain.

If payouts are not part of the product — for example, a marketplace where the platform facilitates introductions but the financial transaction happens off-platform — you can simplify the payment integration to standard payment processing rather than marketplace infrastructure.

When To Use This Template

Use this template when you need to explain:

• a marketplace business model and why it is different from a retail or SaaS product
• the two distinct user populations the system serves and why their incentives and needs differ
• the non-negotiable external dependencies that define the marketplace — payments, real-time sync, trust and safety
• why geographic expansion into new markets is not just an operational concern but an architectural one, due to compliance requirements that differ by jurisdiction
• why trust and safety is a recurring architectural investment rather than a one-time product feature