Every two-sided marketplace eventually hits the same wall: buyers are easy to onboard (an email and a password), but sellers are not. The moment a platform lets a stranger receive money — Amazon Marketplace, Airbnb, Uber, Etsy, Upwork, the App Store — it inherits a set of legal and financial obligations that have nothing to do with the product itself and everything to do with banking regulation, tax law, and fraud prevention.

In the earliest days of e-commerce marketplaces, seller onboarding was manual: a business development person emailed a spreadsheet, someone in finance manually wired a bank account into an accounting system, and a compliance officer eyeballed a scanned passport. This worked when a marketplace onboarded ten sellers a month. It collapses completely at the scale modern platforms operate at — Amazon onboards new third-party sellers continuously worldwide, Airbnb onboards new hosts every minute, and Uber/Lyft onboard new drivers in bulk during city launches. At that volume, onboarding has to be a software system, not a process run by humans reading documents.

The turning point in the industry was the emergence of embedded finance platforms — Stripe Connect (2016), PayPal for Marketplaces, Adyen for Platforms — which productized the three hardest pieces of this problem (identity verification, tax form collection, payout rail connectivity) as APIs that any marketplace could integrate rather than build from scratch. This tutorial designs the system that sits around those integrations: the orchestration layer, the data model, and the scale-out architecture a marketplace needs regardless of which underlying KYC or payments vendor it chooses.

1.1 Why marketplaces cannot skip these checks

It is also worth understanding why marketplaces cannot simply skip or defer these checks the way a typical consumer sign-up flow might defer “verify your email” for a few days. Financial regulation in most jurisdictions makes the platform itself liable if it facilitates payments to an unverified or sanctioned party — this is not a product nicety, it is a legal precondition for the seller ever receiving a single dollar. That legal weight is precisely why onboarding architecture deserves the same rigor as a payments or fraud system, even though on the surface it looks like “just another sign-up form.”

1.2 A short history of onboarding at scale

1.3 Conway’s Law and the three-leg split

This also explains why the three legs of onboarding are so often owned by three different internal teams at a real company: Identity Verification typically sits with a Trust & Safety or Compliance organization, Tax Documentation sits with Finance/Tax, and Payout Setup sits with the Payments team. A system design that forces these three teams to ship changes through one shared, monolithic service creates an organizational bottleneck that mirrors Conway’s Law — the software structure ends up fighting the team structure instead of reflecting it. Designing three independently deployable services from the start avoids that friction as the company scales.

Seller onboarding sits at the intersection of three very different domains, each with its own failure modes and its own external dependencies:

Each of these steps can independently succeed, fail, or get stuck in a “pending manual review” state — and a seller cannot start selling until all three are complete. This creates a distributed, long-running, multi-step workflow that can take anywhere from seconds (an instantly-verified individual seller) to days (a business seller whose incorporation documents need manual review). The system has to track partial progress accurately, resume where it left off, and never silently drop a seller mid-onboarding.

2.1 The scale problem, framed correctly

Layered on top of this workflow complexity is a genuine scale problem. A marketplace running a major promotional push, a city launch, or a seasonal recruiting campaign (e.g., “become a seller for the holiday season”) can see onboarding-related traffic spike enormously — form submissions, document re-uploads, status polling from mobile apps, webhook callbacks from verification vendors — all hitting the edge simultaneously. The requirement to design for millions of requests per minute at the edge is not about millions of new sellers signing up at once (that would be unrealistic); it is about the read-heavy, poll-heavy, webhook-heavy traffic pattern that surrounds a large in-flight onboarding cohort, plus normal platform traffic sharing the same edge infrastructure. Recognizing this distinction early — between the volume of genuinely new work entering the system and the volume of traffic the system’s public surface must absorb — is the single most important framing decision in this entire design, and it recurs explicitly in the Performance & Scalability section later in this tutorial.

2.2 The product dimension: friction leaks sellers

There is a product dimension to this problem too, often underestimated by engineers focused purely on the backend: onboarding funnels leak sellers at every step, and every additional minute of friction increases drop-off. A marketplace that makes a seller wait on a blocking synchronous call for identity verification loses far more applicants than one that lets the seller keep moving (attaching a payout account, browsing seller tools) while identity review happens in the background. This is a strong product argument for the same asynchronous, decoupled architecture that the scale and reliability requirements independently demand — the business incentive and the engineering incentive point the same direction.

2.3 Iteration speed by domain boundary

Finally, the three-domain split has a subtler benefit for iteration speed. A marketplace expanding into a new country typically needs new tax-form logic and possibly a new payout rail, but rarely needs to change how identity verification works. If Tax and Payout are independently deployable services, that expansion is a change scoped to two services with no risk to Identity Verification’s existing, working logic — exactly the kind of blast-radius containment that motivates a microservices boundary in the first place.

3.1 Functional requirements

• A prospective seller can start an application, save progress, and resume later across sessions and devices.
• The system collects identity documents and biometric/liveness data, submits them to a verification vendor, and records the outcome (approved, rejected, needs manual review).
• The system determines the correct tax form per seller type and jurisdiction (e.g., W-9 for US individuals, W-8BEN for non-US individuals, W-9/W-8BEN-E for businesses), validates the submitted Tax Identification Number, and stores the signed form.
• The system collects and validates payout account details (bank account, card, or digital wallet), verifies ownership (e.g., micro-deposits or instant account verification), and links the account to the seller’s profile.
• A seller becomes “active” (able to list products/services and receive payouts) only when all three sub-processes reach an approved state.
• Compliance and support teams can view a seller’s full onboarding history and manually intervene (approve, reject, request re-submission) on any step.
• The system supports re-verification triggers (e.g., periodic re-KYC required by regulation, or a flag raised by a fraud model post-onboarding).

3.2 Non-functional requirements

• Scale: The public-facing edge (API Gateway and Load Balancer tier, CDN, static asset delivery, status-check endpoints) must sustain traffic bursts on the order of millions of requests per minute — roughly 16,000+ requests/second sustained, with burst capacity several multiples higher — without degrading onboarding form submission latency.
• Throughput: Thousands of new seller applications must be processable per day, with the workflow engine able to advance tens of thousands of in-flight onboarding steps concurrently.
• Consistency: A seller must never be marked “active” (able to receive payouts) unless every required step has genuinely passed — this is a hard correctness requirement, not a best-effort one.
• Latency: Form submission and status-check APIs should respond in well under 300ms p99, even though the underlying verification steps themselves are asynchronous and can take minutes to days.
• Auditability: Every decision (approval, rejection, manual override) must be immutably logged with who/what made the decision, for regulatory audits.
• Data protection: Identity documents, tax IDs, and bank details are highly sensitive PII/PCI-adjacent data requiring encryption at rest, strict access control, and jurisdiction-aware data residency.

3.3 Two engineering problems, one system

Taken together, these requirements split cleanly into two very different engineering problems that this tutorial solves separately: a correctness problem (never activate a seller who has not genuinely passed every check, never lose track of a partially-completed application) and a scale problem (survive an edge tier absorbing enormous, bursty, largely read-only traffic). Conflating these two problems — for example, by making the correctness-critical write path try to scale the same way as the read-heavy status endpoint — is the most common architectural mistake in systems like this, and avoiding it shapes almost every design decision in the sections that follow.

The architecture separates a horizontally-scaled, stateless edge tier (built to absorb the million-requests-per-minute traffic pattern) from a set of domain-owned onboarding services, each responsible for one leg of the process, coordinated by a central workflow orchestrator.

5.1 API Gateway Cluster

The single authenticated entry point for every client request. In this system it does more than routing: it distinguishes cheap, cacheable status-check calls from expensive, stateful form-submission calls, and applies different rate-limit tiers to each so that a burst of status polling never starves actual application submissions of capacity.

5.2 Load Balancer

Distributes traffic across a large, autoscaled pool of stateless backend instances. At million-requests-per-minute scale, the load balancer tier itself is deployed as a fleet (not a single box) behind a Layer 4/anycast entry point, with health checks aggressively removing degraded instances from rotation within seconds.

5.3 WAF (Web Application Firewall)

Sits between the CDN and the API Gateway to filter malicious traffic — credential-stuffing attempts against the seller login, scripted bulk-application bots trying to farm referral bonuses, and known attack signatures — before that traffic ever reaches application compute, which is essential when the edge is absorbing millions of requests per minute and cannot afford to spend real backend capacity filtering obvious abuse.

5.4 Onboarding Application Service

Owns the multi-step application form: which sections a seller has completed, draft data for in-progress sections, and validation of individual fields (email format, required fields present) before anything is submitted downstream. Stateless itself; all progress state lives in Redis and the Seller Profile Database.

5.5 Status Query Service

A read-optimized service that answers “what is the current state of my onboarding” without touching the orchestrator or any downstream vendor directly. It reads from a denormalized, cache-friendly view that is updated asynchronously via events, which is what allows it to absorb enormous polling volume cheaply.

5.6 Onboarding Orchestrator

The workflow engine at the center of the system. Tracks each seller’s progress through Identity Verification, Tax Documentation, and Payout Setup as a long-running Saga, calling each domain service, handling asynchronous callbacks/webhooks, applying compensating logic when a step fails, and computing the aggregate “can this seller go active” decision only when every required step is genuinely approved.

5.7 Identity Verification Service

Wraps a third-party KYC/KYB vendor (Persona, Onfido, Jumio, or an in-house solution for regulated markets). Submits documents and biometric data, tracks the vendor’s asynchronous review process, and normalizes vendor-specific outcomes into an internal status model.

5.8 Tax Documentation Service

Determines the correct tax form based on seller type and country, validates the Tax Identification Number format and (where available) against a government TIN-matching API, and stores the completed, e-signed form in the encrypted document store.

5.9 Payout Account Service

Integrates with a payments platform (Stripe Connect, Adyen for Platforms, or direct banking rails) to create a connected payout account, collect and verify bank/card details, and confirm the account is enabled to receive funds in the seller’s jurisdiction.

5.10 Compliance Review Service

Surfaces applications that any automated step flagged for manual review (a mismatched name, a rejected document, a sanctions-list hit) into a queue that human compliance analysts work through, with full context and an audit trail of their decision.

5.11 Notification Service

Sends status updates (document received, verification approved, additional information needed, seller now active) across email/SMS/push, subscribing to the same event bus as every other downstream consumer.

5.12 Analytics and Fraud Pipeline

Consumes onboarding events into a stream-processing/warehouse pipeline to compute funnel drop-off rates per step, detect fraud rings (many applications sharing a device fingerprint or bank account), and feed risk scores back into the Orchestrator to trigger extra scrutiny on suspicious applications.

One design detail worth calling out explicitly: none of these components talk to each other directly. The Identity Verification Service has no API dependency on the Tax Documentation Service, and neither has any awareness that a Payout Account Service even exists. The only component that knows about all three is the Orchestrator, and even it interacts with them exclusively through their public APIs and published events — never through shared database tables or internal method calls. This strict boundary is what allows a team to rewrite the entire Payout Account Service, swap payments vendors, or change its internal data model without coordinating a single line of code change with the Identity or Tax teams.

6.1 Onboarding state machine

As with the order-level status in a fulfillment system, the seller’s overall onboarding status is a derived aggregate computed from the three independent sub-statuses. A seller only transitions to Active when all three sub-processes report an approved state; a rejection in any one of them moves the seller into a rejected or needs-more-info state, without requiring the other two subsystems to know anything about each other.

Identity verification splits into two flows: KYC (Know Your Customer) for individual sellers, and KYB (Know Your Business) for business entities, which requires verifying the business registration, beneficial ownership, and the identity of the individuals who control it. Both flows submit documents to a third-party vendor and receive an asynchronous verdict.

@Service
public class IdentityVerificationService {

    private final KycVendorClient vendorClient;
    private final DocumentStore documentStore;
    private final IdentityVerificationRepository repository;

    public void submitForVerification(SellerId sellerId, IdentityPackage pkg) {
        // Idempotency guard: don't resubmit if already pending or approved
        Optional<IdentityRecord> existing = repository.findLatest(sellerId);
        if (existing.isPresent() && existing.get().getStatus().isTerminalOrPending()) {
            return;
        }

        String docHandle = documentStore.storeEncrypted(pkg.getDocuments());
        VendorSubmissionResult result = vendorClient.submit(
            sellerId.value(), pkg.getSellerType(), docHandle,
            pkg.getLivenessCheckToken());

        IdentityRecord record = new IdentityRecord(
            sellerId, result.getVendorReferenceId(), VerificationStatus.PENDING);
        repository.save(record);
    }

    // Called by the webhook handler when the vendor completes review
    @Transactional
    public void handleVendorCallback(String vendorReferenceId, VendorVerdict verdict) {
        IdentityRecord record = repository.findByVendorReference(vendorReferenceId)
            .orElseThrow(() -> new UnknownVendorReferenceException(vendorReferenceId));

        VerificationStatus newStatus = mapVerdict(verdict);
        record.transitionTo(newStatus, verdict.getReasonCodes());
        repository.save(record);

        eventPublisher.publish(new IdentityStepUpdatedEvent(record.getSellerId(), newStatus));
    }
}

7.1 Handling vendor webhooks reliably

KYC vendors deliver verdicts via webhook, often with at-least-once delivery semantics and no strict ordering guarantee. The webhook handler must be idempotent (keyed on the vendor’s reference ID, not assuming it is the first or only callback for that reference) and must verify webhook signatures to prevent forged approval callbacks — a critical control, since a forged webhook could otherwise be used to fraudulently self-approve identity verification.

@PostMapping("/webhooks/kyc-vendor")
public ResponseEntity<Void> handleWebhook(
        @RequestBody String rawPayload,
        @RequestHeader("X-Vendor-Signature") String signature) {

    if (!signatureVerifier.isValid(rawPayload, signature)) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
    }

    VendorVerdict verdict = payloadParser.parse(rawPayload);
    identityVerificationService.handleVendorCallback(verdict.getReferenceId(), verdict);

    return ResponseEntity.ok().build(); // ack quickly; processing is idempotent
}

7.2 KYB: verifying businesses, not just people

Business sellers add a layer: the platform must verify the business registration itself (e.g., against a corporate registry), identify all beneficial owners above a regulatory ownership threshold (commonly 25% in many jurisdictions), and run each beneficial owner through individual KYC. This means one business application can fan out into multiple parallel identity verification sub-workflows, all of which must complete before the business’s identity step as a whole is considered approved.

This nested aggregation is a useful general lesson: the same “derive the parent status from independent children” pattern that computes a seller’s overall onboarding status from three sub-steps recurses naturally one level deeper inside KYB, computing the identity sub-step’s own status from multiple beneficial-owner records. Recognizing that a system design pattern applies recursively, rather than inventing a new one-off mechanism for the business-ownership case, keeps the codebase and the mental model consistent as new edge cases are discovered.

Tax documentation must determine the correct form based on seller type and residency, since submitting the wrong form is a compliance failure even if the seller filled it out honestly.

public enum TaxFormType {
    W9,           // US individual or entity
    W8BEN,        // Non-US individual
    W8BENE,       // Non-US entity
    LOCAL_VAT_ID  // Jurisdictions requiring VAT/GST registration
}

@Service
public class TaxFormResolver {

    public TaxFormType resolve(SellerType sellerType, String residencyCountry) {
        boolean isUs = "US".equals(residencyCountry);
        if (sellerType == SellerType.INDIVIDUAL) {
            return isUs ? TaxFormType.W9 : TaxFormType.W8BEN;
        } else {
            return isUs ? TaxFormType.W9 : TaxFormType.W8BENE;
        }
    }
}

Once the correct form is presented and completed, the Tax Identification Number itself is validated in two layers: a fast structural check (correct number of digits, valid checksum where applicable) that runs synchronously for instant feedback, and an asynchronous check against a government TIN-matching service (where available, such as the IRS TIN Matching Program in the US) that confirms the number and the associated name actually match on record.

@Service
public class TaxIdValidator {

    public ValidationResult validateStructure(String tin, String country) {
        TinFormatRule rule = formatRules.get(country);
        if (!rule.matches(tin)) {
            return ValidationResult.invalid("TIN format does not match expected pattern");
        }
        return ValidationResult.valid();
    }

    public void submitForNameMatch(SellerId sellerId, String tin, String legalName) {
        // Asynchronous: government matching APIs are often slow or batch-based
        tinMatchingClient.submitAsync(sellerId.value(), tin, legalName);
    }

    @Transactional
    public void handleMatchResult(SellerId sellerId, TinMatchResult result) {
        TaxRecord record = taxRecordRepository.findBySellerId(sellerId);
        record.applyTinMatchResult(result);
        taxRecordRepository.save(record);
        eventPublisher.publish(new TaxStepUpdatedEvent(sellerId, record.getStatus()));
    }
}

8.1 Signed document retention

Completed tax forms are legally required to be retained for a fixed number of years (commonly several years past the last reportable payment in the US for W-9/1099 purposes). The signed PDF, along with an audit record of the e-signature (timestamp, IP address, signature method), is stored in the encrypted document store with a retention policy attached at write time, rather than relying on a manual process to remember to keep it.

Payout setup connects a seller’s bank account, debit card, or digital wallet so the platform can actually send them money. This subsystem almost always integrates with a payments platform rather than connecting directly to banking rails, since building direct ACH/SEPA/card-network connectivity in-house is a massive undertaking most marketplaces reasonably avoid.

@Service
public class PayoutAccountService {

    private final PaymentsPartnerClient partnerClient;
    private final PayoutAccountRepository repository;

    public void createConnectedAccount(SellerId sellerId, SellerProfile profile) {
        ConnectedAccountRequest request = ConnectedAccountRequest.builder()
            .country(profile.getCountry())
            .businessType(profile.getSellerType())
            .email(profile.getEmail())
            .build();

        ConnectedAccountResult result = partnerClient.createAccount(request);

        PayoutAccount account = new PayoutAccount(
            sellerId, result.getExternalAccountId(), PayoutStatus.PENDING_VERIFICATION);
        repository.save(account);
    }

    public void attachBankAccount(SellerId sellerId, BankAccountDetails details) {
        PayoutAccount account = repository.findBySellerId(sellerId);
        partnerClient.attachExternalBankAccount(account.getExternalAccountId(), details);
        // Verification (micro-deposits or instant verification) proceeds
        // asynchronously; status arrives via webhook.
    }

    @Transactional
    public void handleVerificationWebhook(String externalAccountId, PayoutVerificationEvent event) {
        PayoutAccount account = repository.findByExternalId(externalAccountId);
        account.transitionTo(event.isVerified() ? PayoutStatus.VERIFIED : PayoutStatus.FAILED);
        repository.save(account);
        eventPublisher.publish(new PayoutStepUpdatedEvent(account.getSellerId(), account.getStatus()));
    }
}

9.1 Account verification methods

Because verification speed varies so widely by method and market, the Orchestrator treats Payout Setup as genuinely asynchronous and unbounded in duration — the same design principle applied to Identity and Tax — rather than assuming it will always resolve quickly.

Unlike a checkout Saga that completes in seconds, the onboarding Saga is long-running — spanning minutes to weeks — and must persist its state durably between steps rather than holding it in memory, since the process itself is fundamentally asynchronous and interrupted by real-world waiting (a vendor review, a seller returning to confirm micro-deposits).

@Service
public class OnboardingOrchestrator {

    private final OnboardingStateRepository stateRepository;
    private final EventPublisher eventPublisher;

    // Invoked whenever any sub-step publishes a StepUpdated event
    @KafkaListener(topics = "onboarding-step-updates")
    public void onStepUpdated(StepUpdatedEvent event) {
        OnboardingState state = stateRepository.findBySellerId(event.getSellerId());
        state.applyStepUpdate(event.getStep(), event.getStatus());
        stateRepository.save(state);

        AggregateStatus aggregate = evaluateAggregate(state);
        if (aggregate == AggregateStatus.ACTIVE && state.getAggregateStatus() != AggregateStatus.ACTIVE) {
            state.setAggregateStatus(AggregateStatus.ACTIVE);
            stateRepository.save(state);
            eventPublisher.publish(new SellerActivatedEvent(event.getSellerId()));
        } else if (aggregate == AggregateStatus.REJECTED) {
            state.setAggregateStatus(AggregateStatus.REJECTED);
            stateRepository.save(state);
            eventPublisher.publish(new SellerRejectedEvent(event.getSellerId(), state.getRejectionReasons()));
        }
    }

    private AggregateStatus evaluateAggregate(OnboardingState state) {
        if (state.anyStepHardRejected()) {
            return AggregateStatus.REJECTED;
        }
        if (state.allStepsApproved()) {
            return AggregateStatus.ACTIVE;
        }
        return AggregateStatus.UNDER_REVIEW;
    }
}

This is a choreography-leaning orchestration: sub-services still publish their own step-updated events onto the bus, but a central Orchestrator listens to all of them and owns the aggregate-status decision, giving the system one clear place to reason about “is this seller allowed to go live” rather than scattering that logic across three independent services.

CREATE TABLE sellers (
    seller_id         BIGINT PRIMARY KEY,
    email             VARCHAR(255) NOT NULL UNIQUE,
    seller_type       VARCHAR(20) NOT NULL,   -- INDIVIDUAL or BUSINESS
    country           CHAR(2) NOT NULL,
    aggregate_status  VARCHAR(30) NOT NULL,   -- derived, e.g. UNDER_REVIEW, ACTIVE, REJECTED
    created_at        TIMESTAMP NOT NULL,
    updated_at        TIMESTAMP NOT NULL
);

CREATE TABLE identity_verifications (
    verification_id      BIGINT PRIMARY KEY,
    seller_id            BIGINT NOT NULL REFERENCES sellers(seller_id),
    vendor_reference_id  VARCHAR(128) NOT NULL,
    status               VARCHAR(30) NOT NULL,  -- PENDING, APPROVED, REJECTED, NEEDS_INFO
    reason_codes         TEXT NULL,
    reviewed_at          TIMESTAMP NULL,
    INDEX idx_seller (seller_id),
    INDEX idx_vendor_ref (vendor_reference_id)
);

CREATE TABLE tax_records (
    tax_record_id     BIGINT PRIMARY KEY,
    seller_id         BIGINT NOT NULL REFERENCES sellers(seller_id),
    form_type         VARCHAR(20) NOT NULL,
    tin_last_four     CHAR(4) NOT NULL,       -- never store full TIN unencrypted
    status            VARCHAR(30) NOT NULL,
    document_handle   VARCHAR(255) NOT NULL,  -- pointer to encrypted document store
    signed_at         TIMESTAMP NULL
);

CREATE TABLE payout_accounts (
    payout_account_id    BIGINT PRIMARY KEY,
    seller_id            BIGINT NOT NULL REFERENCES sellers(seller_id),
    external_account_id  VARCHAR(128) NOT NULL,  -- reference into payments partner
    status               VARCHAR(30) NOT NULL,
    verification_method  VARCHAR(30) NOT NULL,
    verified_at          TIMESTAMP NULL
);

CREATE TABLE onboarding_audit_log (
    audit_id       BIGINT PRIMARY KEY,
    seller_id      BIGINT NOT NULL,
    step           VARCHAR(20) NOT NULL,
    old_status     VARCHAR(30) NULL,
    new_status     VARCHAR(30) NOT NULL,
    actor          VARCHAR(64) NOT NULL,   -- system, vendor-webhook, or a compliance analyst id
    occurred_at    TIMESTAMP NOT NULL
);

Notice full Tax Identification Numbers are never stored in plaintext in this table — only the last four digits for display purposes, with the full value held in a dedicated, heavily access-controlled secrets/encryption service (or tokenized via the payments partner) and referenced by a handle. The onboarding_audit_log table is append-only and is the system’s answer to “prove to a regulator exactly what happened and when” for any given seller.

{
  "sellerId": "slr_7Q2M9",
  "aggregateStatus": "UNDER_REVIEW",
  "steps": {
    "identity": { "status": "APPROVED", "updatedAt": "2026-08-01T14:02:00Z" },
    "tax":      { "status": "NEEDS_INFO", "reason": "TIN name mismatch" },
    "payout":   { "status": "PENDING", "verificationMethod": "MICRO_DEPOSIT" }
  }
}

The GET status endpoint is deliberately the highest-traffic endpoint in the whole system, since mobile clients typically poll it every few seconds while an application is in review. It never calls the Orchestrator or any downstream vendor synchronously — it reads exclusively from the denormalized, cache-backed view maintained by the Status Query Service, which is what makes it survivable at the traffic volumes described in the requirements.

13.1 Caching strategy for the status endpoint

Because status queries dominate traffic, the Status Query Service caches each seller’s current status document in Redis, keyed by seller ID, with cache invalidation driven by the same StepUpdated/SellerActivated events every other consumer subscribes to — not by TTL expiry. This means the cache is always at most a few hundred milliseconds stale (the time to process an event) rather than stale for an entire TTL window, while still absorbing the overwhelming majority of read traffic without touching the primary database at all.

@Service
public class StatusQueryService {

    private final RedisTemplate<String, String> redis;
    private final StatusViewRepository fallbackRepository;

    public OnboardingStatusView getStatus(SellerId sellerId) {
        String cached = redis.opsForValue().get(cacheKey(sellerId));
        if (cached != null) {
            return deserialize(cached);
        }
        // Cache miss fallback: read from the durable, denormalized view table
        OnboardingStatusView view = fallbackRepository.findBySellerId(sellerId);
        redis.opsForValue().set(cacheKey(sellerId), serialize(view), Duration.ofMinutes(10));
        return view;
    }

    @KafkaListener(topics = {"onboarding-step-updates", "seller-activated"})
    public void onStatusChanged(Object event) {
        SellerId sellerId = extractSellerId(event);
        OnboardingStatusView updated = fallbackRepository.findBySellerId(sellerId);
        redis.opsForValue().set(cacheKey(sellerId), serialize(updated), Duration.ofMinutes(10));
    }

    private String cacheKey(SellerId id) { return "onboarding:status:" + id.value(); }
}

13.2 Database choices

The core Seller/Identity/Tax/Payout records need strong consistency and are relatively low-write-volume (thousands of applications a day, not millions of writes a second), making a sharded relational database (PostgreSQL, or a distributed SQL system for very large platforms) the right fit. The audit log, by contrast, is append-only and extremely well suited to a write-optimized, horizontally-scalable store — many platforms route audit events into both the relational store (for quick lookups) and a data lake/warehouse (for long-term compliance retention and analytics).

13.3 Load balancing at million-request scale

Splitting Identity, Tax, and Payout into independently owned services coordinated by an Orchestrator buys resilience and independent scalability at the cost of operational complexity — three (or more) services, three vendor integrations, and a distributed workflow that is inherently harder to reason about than a single synchronous signup form.

It is worth being explicit that this trade-off is not free even when it is the right call. A smaller marketplace onboarding a handful of sellers a week may reasonably choose a simpler, more monolithic implementation and revisit the split once volume and organizational complexity justify it — the architecture in this tutorial is aimed squarely at the “thousands of sellers a day, multiple owning teams, global regulatory footprint” scale named in the requirements, and over-engineering toward it prematurely carries its own real cost in development speed and operational overhead.

A million requests per minute is roughly 16,700 requests/second sustained, with realistic burst peaks several times that. Designing for this number means treating the edge tier and the domain-service tier as having fundamentally different scaling requirements, and never letting the slower tier become a dependency of the faster one.

15.1 The read-heavy edge

15.2 The write-light, latency-tolerant core

• Actual application submissions, document uploads, and vendor webhook callbacks are orders of magnitude lower in volume than status reads — thousands to tens of thousands per day, not per second — so the Orchestrator, Identity, Tax, and Payout services can be provisioned for a much smaller, steadier baseline load with autoscaling headroom for daily/weekly patterns (e.g., a Monday morning surge) rather than for the same peak as the edge tier.
• Document uploads (identity photos, tax forms) go directly from the client to object storage via a pre-signed upload URL, bypassing application servers entirely for the actual file bytes — the backend only ever handles a small metadata record and a storage handle, which keeps large binary traffic off the request path that needs to stay fast.

15.3 Working through a capacity example

Consider a city-launch campaign where 50,000 new sellers apply over a single day, each polling their status roughly every 10 seconds for an average of 20 minutes of active app usage per day during the review period. That is 50,000 × 120 polls = 6,000,000 status requests spread across the day — a modest number compared to the platform’s baseline traffic from all other sellers and buyers, which is exactly the scenario the million-requests-per-minute requirement is really describing: onboarding’s own write volume stays small, while it shares an edge tier engineered for the platform’s total load.

15.4 Graceful degradation under extreme load

Even a well-architected edge tier benefits from an explicit degradation strategy for the rare moment traffic exceeds even generous provisioning — a coordinated bot attack, a client-side bug causing a polling storm, or a genuine record-breaking traffic event. Rather than letting the whole platform fail uniformly, the Status Query Service should be able to shed load gracefully: serving a slightly staler cached response with an extended TTL under pressure, returning a clear “retry after N seconds” response with a Retry-After header instead of a hard error, and prioritizing authenticated, known-good traffic over anonymous or newly-seen clients when the system must choose who to serve first. This kind of load-shedding logic belongs at the API Gateway and Status Query Service specifically, since they are the components actually absorbing the million-requests-per-minute traffic pattern described in the requirements.

• Encryption everywhere sensitive: Identity documents, tax IDs, and bank details are encrypted at rest (field-level encryption for the most sensitive fields like full TIN) and in transit (TLS everywhere, including internal service-to-service calls).
• Least-privilege access: Only the Identity Verification Service can read raw identity documents; only the Tax Documentation Service (and a narrowly scoped compliance tool) can read full TINs; the Orchestrator only ever sees status enums, never the underlying sensitive payloads.
• Webhook signature verification on every inbound vendor callback, as shown earlier, to prevent forged approval events.
• PII minimization and data residency: Sensitive documents are stored in region-appropriate storage to satisfy data-residency regulations (e.g., EU seller documents stored in EU-region infrastructure), and retained only as long as legally required before secure deletion.
• Fraud and abuse detection: Velocity checks on applications per device/IP, cross-referencing bank account numbers and identity documents across applications to catch the same fraud ring attempting to onboard many fake seller identities, and step-up friction (additional document requests) for applications matching known fraud patterns.
• Audit-everything: Every automated decision and every human override is logged immutably with actor identity, satisfying both internal security review and external regulatory audit requirements.

17.1 Threat modeling the onboarding pipeline specifically

Onboarding is an attractive target precisely because it sits upstream of money movement — an attacker who successfully onboards a fraudulent seller identity gains a channel to receive payouts, launder funds through fake sales, or harvest referral/promotional incentives at scale. A useful threat-modeling exercise is to walk each of the three subsystems and ask “what does an attacker gain by subverting just this one step, without needing the other two?” Subverting Identity alone (e.g., synthetic identity fraud, using a mix of real and fabricated identity attributes) gains little without a working payout account attached, which is exactly why the aggregate-status gate requiring all three steps to independently pass is a meaningful security control, not just a workflow convenience — an attacker who can fool one vendor’s automated check still has to clear two more independent barriers.

Every request carries a correlation ID from the original application submission through every downstream service call, webhook, and event, enabling full-journey tracing for a specific seller’s onboarding in tools like Jaeger or Zipkin — essential when a compliance or support inquiry requires reconstructing exactly what happened and when.

Each service is independently deployable via Kubernetes, with horizontal pod autoscalers tuned to that service’s actual traffic pattern — the Status Query Service and API Gateway scale aggressively and quickly in response to request rate, while the Orchestrator, Identity, Tax, and Payout services scale on a much gentler curve tied to application submission volume.

• CI/CD: Canary deployments for the edge tier and Orchestrator specifically, given their criticality; a bad deploy to the Status Query Service directly degrades the platform’s ability to serve its highest-traffic endpoint.
• Infrastructure as Code: Terraform manages the Kafka cluster, database clusters, Redis clusters, and autoscaling policies, keeping staging and production environments reproducible and making capacity changes auditable.
• Multi-region for the edge, regional for compliance-sensitive services: The CDN, WAF, and API Gateway run active-active across regions globally; the Identity and Tax services, by contrast, may need to be deployed per-region with data residency boundaries respected, since a European seller’s identity documents may be legally required to stay within EU infrastructure.
• Cost optimization: The bursty, read-heavy edge tier is a good fit for aggressive autoscaling and CDN offload to minimize idle compute cost; the steadier domain-service tier can run on more predictably-sized, reserved capacity.

20.1 Patterns used

20.2 Anti-patterns to avoid

• Synchronous fan-out at signup: Making the initial application-submission request block on all three vendor integrations completing — this directly couples checkout-style latency expectations to processes that can legitimately take days.
• God Orchestrator: Letting the Orchestrator directly implement KYC document validation logic or tax form parsing itself, rather than delegating to the owning domain service — this recreates a monolith with extra network hops.
• Trusting client-reported status: Allowing a mobile client to claim “identity approved” without the backend independently verifying against the Identity Verification Service’s own record — all activation decisions must be server-side and vendor-verified.
• One-size-fits-all rate limiting: Applying the same rate limit to the high-volume Status Query endpoint and the low-volume application-submission endpoint, which either throttles legitimate polling or leaves the write path under-protected.

• Do model each onboarding step’s status independently and derive the aggregate — never collapse three independent processes into one flat “onboarding status” enum.
• Do make every webhook handler idempotent and signature-verified from day one; retrofitting this after a production incident is far more painful than building it in from the start.
• Do separate the read-heavy status-check path from the write path architecturally (CQRS), especially given a scale requirement measured in requests per minute rather than applications per day.
• Do not assume a seller’s onboarding will complete quickly — design the data model, notification cadence, and SLA-escalation logic around processes that can legitimately take days to weeks.
• Do not let any single onboarding step’s vendor outage block the other two steps from progressing — decouple them fully, exactly as digital and physical fulfillment are decoupled in an order-fulfillment system.
• Do build the Compliance Review queue as a first-class feature from launch, not an afterthought — automated KYC/tax/payout checks will never achieve 100% straight-through processing, and a platform without a good manual-review tool will bottleneck on ad hoc spreadsheets and Slack threads instead.
• Do instrument time-to-active and per-step drop-off as product metrics from day one, not just technical SLA metrics — a step that is technically fast but confusingly worded can leak just as many sellers as a step that is technically slow.
• Do not hard-code jurisdiction-specific rules (which tax form applies, which identity document types are accepted, which payout rails exist) directly into service logic — externalize them into configuration or a rules engine, since a marketplace expanding into new countries will need to add and adjust these rules constantly without a full redeploy.
• Do give Compliance analysts a single-pane view of a seller’s entire onboarding journey (all three steps, all vendor responses, all prior manual notes) rather than three separate tools per domain — the org chart may be split three ways, but the human reviewing an edge case needs the full picture in one place.

Across all of these examples, the common architectural thread is the same: the seller/host/driver-facing experience is a single, unified checklist, while the backend genuinely runs three-plus independent pipelines with different vendors, different latencies, and different failure modes — exactly the separation of concerns this tutorial’s Orchestrator and per-step state machine are designed to express cleanly in code and in data.

The throughline across this design is the same principle that governs almost every large-scale marketplace system: keep the customer-facing (here, seller-facing) experience simple and unified — one application, one status page — while pushing the real complexity into independently scaling, independently failing backend services connected by durable, asynchronous workflows rather than fragile synchronous chains. Get that separation right, and the system can absorb a city launch, a holiday recruiting campaign, or a new country’s regulatory requirements without the underlying architecture needing to change — only the configuration and the scale of each already-independent piece.