Every marketplace that connects strangers to trade goods or services — eBay, Amazon, Etsy, Airbnb, Upwork, Flipkart — eventually runs into the same hard problem: what happens when a buyer and a seller disagree? The buyer says the shoes never arrived. The seller says they shipped them. The buyer says the laptop was “like new” but arrived scratched. Someone has to decide who is right, and someone has to move money, reputation, or goods accordingly.

This is the job of a Dispute Resolution System (DRS). It is one of the least glamorous but most business-critical systems inside any marketplace, because it directly controls trust. If disputes are resolved slowly, unfairly, or inconsistently, buyers stop buying and sellers stop selling. Everything else the marketplace has built — search, recommendations, checkout, logistics — runs downstream of that trust.

1.1 A short history

In the early days of e-commerce (late 1990s), disputes were handled almost entirely by humans: email support agents reading complaints and manually deciding refunds. This didn’t scale. As marketplaces like eBay grew into millions of daily transactions, companies built dedicated “Trust & Safety” or “Resolution Center” platforms — software that could log disputes, attach evidence, and route cases to the right queue.

Over the 2010s, three big shifts happened:

• Self-service case creation — buyers and sellers could open a dispute themselves through an app instead of calling support.
• Structured evidence capture — instead of free-text emails, systems started asking for photos, tracking numbers, and structured reason codes, making cases easier to compare, aggregate, and automate.
• Automated / rules-based resolution — for simple, repetitive cases (for example, “package marked delivered but buyer says not received, and it’s under $20”), machine logic started resolving cases in seconds instead of routing everything to a human agent.

Modern systems (2020s onward) combine rules engines, machine learning risk scoring, and human review queues into a hybrid pipeline — which is exactly the kind of system this tutorial will design from scratch. The point of walking through the historical arc first is that each layer of today’s architecture is not arbitrary; it was added specifically to solve a pain that its predecessor generation left behind, and knowing which pain each layer answers is what lets you make sensible choices when you inevitably have to trim scope for a smaller marketplace.

Let’s be precise about what we’re solving. A marketplace dispute resolution system must let a buyer or seller do all of the following, reliably and at scale.

• Open a case against an order (“item not received,” “item not as described,” “seller not responding,” “payment not received,” etc.).
• Attach evidence — photos, videos, PDFs, chat logs, tracking numbers.
• Track the status of the case in real time.
• Communicate with the other party and/or a mediator inside the case thread.
• Receive a fair, explainable resolution — automatically for simple cases, or via a human agent for complex ones.

2.1 Business goals

Before any architecture diagram, we need shared vocabulary. Every design decision later reduces to a choice between these primitives, and interviewers will happily probe any of them.

3.1 Dispute / Case

A case is the central object: it represents one disagreement tied to one order between a buyer and a seller. It has a lifecycle (open → evidence collection → under review → resolved → closed → possibly appealed → re-opened).

3.2 Evidence

Evidence is any file or structured data submitted to support a party’s claim — photos, videos, shipment tracking data, chat transcripts, invoices. Evidence must be stored immutably (never silently edited) once submitted, because it may later be reviewed by a human agent, an appeals team, or in rare cases a real court.

3.3 Reason Codes

Instead of free text, most systems ask the buyer/seller to pick from a fixed list of reason codes (for example, ITEM_NOT_RECEIVED, ITEM_NOT_AS_DESCRIBED, DAMAGED_IN_TRANSIT, WRONG_ITEM, SELLER_UNRESPONSIVE). This is what makes automation possible — you can’t write a rule against unlimited free text, but you can write a rule against “reason = ITEM_NOT_RECEIVED AND order_value < $25 AND tracking shows delivered AND buyer has < 2 prior disputes this quarter.”

3.4 Resolution

The outcome of a case: full refund, partial refund, replacement, no action, or account penalty. Resolutions can be automated (a rules engine or ML model decides) or manual (a human trust and safety agent decides).

3.5 SLA (Service Level Agreement)

An internal promise about how fast a case type must be handled — for example, “auto-resolvable cases must decide within 30 seconds; agent-reviewed cases must get a first response within 24 hours.” SLAs are the metric that turns fairness from an abstract goal into an operational one that on-call engineers can page on.

3.6 Escrow / Payment Hold

Many marketplaces don’t release a seller’s payout the instant an order ships — they hold funds for a window (or until delivery confirmation) precisely so that if a dispute is opened, there is money available to refund without having to claw it back from a seller who may have already withdrawn it. The dispute resolution system needs to know, for every case, whether funds are still held or have already been released, because that changes which resolution actions are even possible.

3.7 Mediation vs. Arbitration

Mediation is when the system (or a human agent) simply facilitates buyer and seller talking to each other and reaching their own agreement — the platform doesn’t impose a decision. Arbitration is when the platform itself renders a binding decision because the two parties can’t agree, or because the case type doesn’t allow direct negotiation (for example, a safety complaint). Our case state machine supports both: a case can sit in a “negotiation” sub-state where only messaging happens, and only escalates to arbitration (automated or agent-driven) if negotiation times out or either party requests it.

3.8 Chargeback

A chargeback happens when a buyer disputes a charge directly with their bank or card network instead of through the marketplace’s own dispute system. This is important architecturally because a chargeback can arrive from an external system (a payment processor webhook) at any time, even for an order that already has, or never had, an internal case — so the Case Service must be able to create or link a case from an external trigger, not only from a buyer clicking “open a dispute” in the app.

3.9 Reputation / Trust Score

A rolling score attached to each buyer and seller account reflecting dispute history, on-time shipping, and resolution outcomes. This score feeds the ML risk model (section 9) and is also surfaced to the human agent console so an agent reviewing a case immediately sees whether they’re dealing with a long-trusted seller or a brand-new, high-risk account.

Requirements come in two flavors: what the system must let users do (functional), and how well it must do it under stress (non-functional). Both matter equally in a design interview.

4.1 Functional requirements

• Buyer/seller can open a dispute against an eligible order.
• Both parties can upload evidence (images, video, PDF, text) tied to a case.
• Both parties can view real-time case status and timeline.
• System auto-resolves eligible simple cases using rules plus risk scoring.
• Complex cases route to a human agent queue with all evidence pre-summarized.
• Either party can appeal a resolution once.
• Admins/agents can search, filter, and bulk-manage cases.
• Full audit trail per case (who did what, when, and why).

4.2 Non-functional requirements

Below is the high-level architecture. Every box names the actual component involved (not just a generic layer), because at this scale the specific technology choice at each hop is part of the design, not an implementation detail to defer.

5.1 Component-by-component explanation

CDN + WAF (edge layer)

Before a request even reaches our data centers, static assets (JS, CSS, evidence-upload UI) are served from CDN edge nodes, and a Web Application Firewall blocks obviously malicious traffic (SQL injection attempts, known bad IPs, volumetric DDoS). This is the first scale lever: it removes a large fraction of the “million requests a minute” from ever hitting application servers.

API Gateway

The API Gateway is the single front door for all client traffic. It does authentication (validating JWT/OAuth tokens), coarse-grained rate limiting per user/IP, request routing to the right backend service, and request/response logging. Centralizing this avoids every microservice re-implementing auth and throttling.

Load Balancers (Global L4 + Regional L7)

We use two layers: a global Layer-4 load balancer (or GSLB/GeoDNS) to route users to their nearest healthy region, and a regional Layer-7 load balancer to distribute traffic across service instances based on HTTP-level routing (path, headers). L7 also enables canary releases — routing 5% of traffic to a new version of the Case Service.

Case Service

A stateless Java microservice owning the case lifecycle state machine: create case, transition status, attach party comments, and enforce eligibility rules (for example, “you can only dispute an order within 60 days of delivery”). Being stateless means we can horizontally scale it to hundreds of pods behind Kubernetes without any sticky-session complexity.

Evidence Service

Handles evidence uploads. It doesn’t store files in a database — it generates a pre-signed upload URL so the client uploads large files (photos/videos) directly to object storage, bypassing our application servers entirely for the heavy bytes. This is critical for scale: our servers only handle small JSON metadata requests, not gigabytes of video.

Resolution Engine Service

The brain of automation. It combines a rules engine (deterministic, explainable if-this-then-that logic) with an ML risk-scoring model (probabilistic fraud/behavior signal) to decide: auto-resolve now, or route to a human agent.

Message Queues (Kafka)

Kafka decouples every stage of the pipeline. When a case is created, the Case Service doesn’t call the Resolution Engine directly (a synchronous call chain would collapse under load) — it publishes a case-created event and returns immediately. The Resolution Engine consumes events at its own pace, which absorbs traffic spikes.

Ledger Service

A separate service purely for money movement (refunds, holds, payouts), backed by a strongly-consistent database, because financial correctness cannot be eventually consistent. It’s isolated from the rest of the system so a bug in, say, the notification service can never touch money.

Human Agent Queue + Search Index

Cases that fail auto-resolution land in a prioritized queue for trust and safety agents, backed by Elasticsearch so agents can search or filter thousands of open cases by reason code, order value, region, or SLA breach risk.

Let’s trace exactly what happens, component by component, when a buyer opens a dispute — this is the sequence an interviewer usually wants you to narrate on a whiteboard.

Notice that the client gets an immediate response (case created) long before the resolution logic even runs. This asynchronous hand-off is what lets the write path stay fast under a million-requests-a-minute load: the Case Service’s job is small (validate, persist, publish), and the heavier decision logic happens off the request path.

6.1 Case state machine

Every arrow above is a guarded transition. For example, OPEN → EVIDENCE_COLLECTION only fires once at least one evidence item is attached or a timer expires, and APPEALED → ESCALATED_TO_AGENT only fires once per case, since each party gets exactly one appeal, enforced at the service layer, not just in the UI.

A dispute case moves through predictable phases. Understanding the data flow at each phase tells you which storage system and which consistency model to use.

7.1 Phase 1: Creation

Buyer submits reason code and order ID. Case Service validates order eligibility (order exists, is within the dispute window, hasn’t already got an open case) against the order database, then writes a new row to the sharded case table with status OPEN. This is a synchronous, strongly consistent write — the buyer must see their case exists immediately after creation.

7.2 Phase 2: Evidence Collection

Both parties can attach evidence for a configurable window (for example, 48 hours). Evidence bytes go straight to object storage via pre-signed URLs; only lightweight metadata (file id, uploader, timestamp, content-type) is written synchronously to the case’s timeline table.

7.3 Phase 3: Automated Review

Once evidence collection closes (or both parties confirm “no more evidence”), a case-ready-for-review event triggers the Resolution Engine. This is an asynchronous, queue-driven phase — the buyer isn’t waiting on a live HTTP connection, they’re polling or getting a push notification.

7.4 Phase 4: Resolution

Either the automated engine issues a decision, or the case is escalated to a human agent. A resolution event triggers the Ledger Service (if money moves) and the Notification Service.

7.5 Phase 5: Appeal or Close

If neither party appeals within the appeal window, the case auto-closes. If appealed, it re-enters the queue with a flag that forces human review (automated systems don’t get a second try on the same case).

Evidence handling deserves its own deep dive because it’s the part of the system most exposed to large binary payloads, abuse (malware uploads, illegal content), and storage cost at scale.

8.1 Direct-to-storage upload flow

Why this design matters at scale: if every evidence photo or video passed through our application servers, a single flash-sale-triggered dispute spike could mean gigabytes per second flowing through stateless compute we’d have to massively over-provision. By letting the client upload directly to object storage, our servers only ever handle small JSON requests for signed URLs — the heavy lifting is delegated to a storage system built for exactly that.

8.2 Content safety scanning

Every uploaded file is asynchronously scanned for malware and, where applicable, run through an image/video moderation model (to catch things like uploaded evidence containing unrelated illegal content). Evidence is not visible to the other party or an agent until it passes scanning — its state sits as PENDING_SCAN until then.

8.3 Immutability & chain of custody

Once evidence is submitted, it is never overwritten. If a user wants to “replace” a photo, the system creates a new evidence record and marks the old one SUPERSEDED — the old file remains retrievable. This matters because appeals and legal escalations sometimes need to see exactly what was originally submitted.

8.4 Sample Java: generating a pre-signed upload URL

@Service
public class EvidenceUploadService {

    private final S3Presigner presigner;
    private static final long MAX_FILE_SIZE_BYTES = 25L * 1024 * 1024; // 25 MB
    private static final Set<String> ALLOWED_TYPES =
        Set.of("image/jpeg", "image/png", "video/mp4", "application/pdf");

    public EvidenceUploadService(S3Presigner presigner) {
        this.presigner = presigner;
    }

    public PresignedUploadResponse createUploadUrl(String caseId, String userId,
                                                     String contentType, long sizeBytes) {
        if (!ALLOWED_TYPES.contains(contentType)) {
            throw new UnsupportedEvidenceTypeException(contentType);
        }
        if (sizeBytes > MAX_FILE_SIZE_BYTES) {
            throw new EvidenceTooLargeException(sizeBytes);
        }

        String objectKey = "evidence/%s/%s/%s".formatted(
            caseId, userId, UUID.randomUUID());

        PutObjectRequest putRequest = PutObjectRequest.builder()
            .bucket("marketplace-dispute-evidence")
            .key(objectKey)
            .contentType(contentType)
            .metadata(Map.of("case-id", caseId, "uploader-id", userId))
            .build();

        PresignedPutObjectRequest presigned = presigner.presignPutObject(
            b -> b.signatureDuration(Duration.ofMinutes(5)).putObjectRequest(putRequest));

        return new PresignedUploadResponse(presigned.url().toString(), objectKey,
            Instant.now().plus(Duration.ofMinutes(5)));
    }
}

This is the component that gives the system its scale advantage: the more cases it can safely resolve without a human, the cheaper and faster the whole system is. But automating a decision that involves someone’s money is risky if done carelessly, so this engine is deliberately layered.

9.1 Two-layer decision model

9.2 Example rule

RULE "auto_refund_low_value_not_received"
WHEN
    reasonCode == "ITEM_NOT_RECEIVED"
    AND orderValue < 25.00
    AND trackingStatus != "DELIVERED_WITH_PHOTO_PROOF"
    AND buyer.disputesLast90Days <= 1
    AND riskScore < 0.20
THEN
    resolution = FULL_REFUND_TO_BUYER;
    holdSellerPayout = false;
    explanation = "Low value, low risk, no delivery photo proof on file";
END

9.3 Sample Java: rules gate combined with risk score

@Service
public class ResolutionDecisionService {

    private final RiskScoringClient riskClient;
    private final RulesEngine rulesEngine;
    private final LedgerClient ledgerClient;
    private final AuditLogger auditLogger;

    public ResolutionDecision decide(CaseFacts facts) {
        double riskScore = riskClient.score(facts);

        if (riskScore >= 0.20) {
            auditLogger.log(facts.caseId(), "ESCALATED_HIGH_RISK", riskScore);
            return ResolutionDecision.escalate(facts.caseId(), "risk_score_too_high");
        }

        Optional<RuleMatch> match = rulesEngine.evaluate(facts);
        if (match.isEmpty()) {
            auditLogger.log(facts.caseId(), "ESCALATED_NO_RULE_MATCH", riskScore);
            return ResolutionDecision.escalate(facts.caseId(), "no_matching_rule");
        }

        RuleMatch rule = match.get();
        ledgerClient.executeResolution(facts.caseId(), rule.outcome());
        auditLogger.log(facts.caseId(), "AUTO_RESOLVED", rule.explanation());

        return ResolutionDecision.autoResolved(facts.caseId(), rule.outcome(), rule.explanation());
    }
}

9.4 Why explainability matters

Every auto-resolution stores the exact rule name and the fact values that triggered it. This isn’t optional polish — regulators, appeals teams, and even the buyer or seller themselves can ask why they were refunded or denied, and the system must answer with a specific reason, not “the algorithm decided.”

Before going deeper into storage and scaling, it’s worth pausing on the underlying computer-science building blocks this system leans on. These aren’t academic detours — each one directly explains a design decision made earlier in this document.

10.1 CAP Theorem applied to this system

The CAP theorem says a distributed system can only fully guarantee two of three properties during a network partition: Consistency, Availability, and Partition tolerance. Since network partitions are a fact of life at scale, the real choice is between consistency and availability when a partition happens. This system deliberately makes different choices for different data:

10.2 Consensus and leader election

Our sharded PostgreSQL clusters use a consensus-based failover mechanism (via tools like Patroni, which itself relies on a consensus store such as etcd, built on the Raft algorithm) to elect a new primary if the current one fails. Raft ensures that even though multiple nodes could theoretically claim to be “the leader” after a failure, only one is ever accepted by a majority of the cluster, preventing a dangerous split-brain scenario where two nodes both think they can accept writes.

10.3 Replication strategies

Within a region, we use synchronous replication to at least one standby, meaning a write isn’t acknowledged to the application until it’s durably stored on more than one node — this protects against losing a case or a refund record if a single machine dies. Across regions, we use asynchronous replication, trading a small window of potential data loss (typically sub-second) for much lower write latency, since waiting for a round trip to another continent on every write would make the system far too slow for a million-requests-a-minute target.

10.4 Partitioning (sharding) strategy

We use a variant of consistent hashing to map buyer_id to a shard. Plain modulo hashing (hash(id) mod N) has a serious weakness: adding or removing a shard (N changes) reshuffles almost every key’s assigned shard, forcing a massive, disruptive data migration. Consistent hashing arranges shards on a conceptual ring so that adding or removing one shard only remaps the small fraction of keys that fell between the old and new boundary, not the entire dataset.

public class ConsistentHashRing {

    private final TreeMap<Long, String> ring = new TreeMap<>();
    private final int virtualNodesPerShard = 150;

    public void addShard(String shardId) {
        for (int i = 0; i < virtualNodesPerShard; i++) {
            long hash = hash(shardId + "#" + i);
            ring.put(hash, shardId);
        }
    }

    public String getShardFor(String buyerId) {
        long hash = hash(buyerId);
        Map.Entry<Long, String> entry = ring.ceilingEntry(hash);
        if (entry == null) {
            entry = ring.firstEntry(); // wrap around the ring
        }
        return entry.getValue();
    }

    private long hash(String key) {
        return Hashing.murmur3_128().hashString(key, StandardCharsets.UTF_8).asLong();
    }
}

Using many “virtual nodes” per physical shard (150 in the example above) spreads the hash ring evenly, avoiding the situation where one shard randomly ends up owning a much larger slice of the ring, and therefore a disproportionate amount of traffic, than the others.

10.5 Priority queue for the agent workload

The Human Agent Queue doesn’t process cases strictly first-in-first-out. It uses a priority queue (min-heap) ordered by a composite score of SLA deadline proximity and case risk, so a case that’s about to breach its SLA, or one flagged as high fraud risk, jumps ahead of a routine case that still has hours of buffer left.

public class AgentPriorityQueue {

    record QueuedCase(String caseId, Instant slaDeadline, double riskScore) {}

    private final PriorityQueue<QueuedCase> heap = new PriorityQueue<>(
        Comparator.comparingDouble(this::priorityScore));

    private double priorityScore(QueuedCase c) {
        long secondsToDeadline = Duration.between(Instant.now(), c.slaDeadline()).getSeconds();
        // Lower score = higher priority. Urgent deadlines and high risk both lower the score.
        return secondsToDeadline - (c.riskScore() * 3600);
    }

    public void enqueue(QueuedCase c) {
        heap.offer(c);
    }

    public Optional<QueuedCase> nextForAgent() {
        return Optional.ofNullable(heap.poll());
    }
}

10.6 Concurrency control: optimistic locking

Two actors, such as an agent manually resolving a case at the same moment the automated engine finishes its own review, could race to update the same case row. Rather than locking the row pessimistically (which would hurt throughput at scale), we use optimistic concurrency control: every case row carries a version column, and an update only succeeds if the version matches what was read; otherwise it’s retried or rejected with a conflict, forcing whichever actor lost the race to re-read the latest state before acting again.

UPDATE cases
SET status = :newStatus, version = version + 1, updated_at = now()
WHERE id = :caseId AND version = :expectedVersion;
-- application checks affected row count; 0 rows means a concurrent update won the race

10.7 Networking considerations

Internal service-to-service calls use HTTP/2 (via gRPC for latency-sensitive internal calls like risk scoring) to benefit from multiplexed connections and lower overhead compared to opening a new connection per request. Client-to-gateway traffic stays on standard HTTPS/REST for broad compatibility with web and mobile clients. Keep-alive connection pools between services avoid the cost of repeated TCP and TLS handshakes under high request rates.

10.8 Failure recovery

Every asynchronous step (evidence scanning, resolution processing, notification sending) is designed to be safely retryable: consumers commit their Kafka offset only after successfully completing their work, so a crash mid-processing simply means the event is redelivered and reprocessed, not lost. Idempotency keys (section 13.3) ensure this redelivery never causes duplicate side effects like double refunds.

No architecture is free. Being honest about what this one gives up in exchange for what it delivers is what turns a design into a defensible one under interviewer pressure or an architecture review.

11.1 Advantages of this architecture

11.2 Key trade-off summary

Different data has different needs. Choosing one datastore for everything at this scale is one of the fastest ways to guarantee a rewrite in two years, so we deliberately mix stores.

12.1 Why sharded PostgreSQL for case data

Case and evidence-metadata records are relational, transactional, and need strong consistency for state transitions, so we use PostgreSQL rather than a pure NoSQL store. But a single PostgreSQL instance cannot handle a million-requests-a-minute write and read load, so we shard by marketplace_region combined with a hash of buyer_id. Every case query in normal operation already includes the buyer or seller ID, so this shard key keeps almost all queries single-shard.

12.2 Caching strategy

Redis sits in front of the case database for the hottest read path: “get case status.” Because status changes are relatively infrequent compared to how often a buyer refreshes their case page, a cache-aside pattern with a short TTL (say, 5 seconds) plus explicit invalidation on write dramatically cuts database load.

@Service
public class CaseStatusReader {

    private final RedisTemplate<String, CaseStatusView> redis;
    private final CaseRepository caseRepository;
    private static final Duration TTL = Duration.ofSeconds(5);

    public CaseStatusView getStatus(String caseId) {
        String cacheKey = "case:status:" + caseId;
        CaseStatusView cached = redis.opsForValue().get(cacheKey);
        if (cached != null) {
            return cached;
        }

        CaseStatusView fresh = caseRepository.findStatusView(caseId)
            .orElseThrow(() -> new CaseNotFoundException(caseId));

        redis.opsForValue().set(cacheKey, fresh, TTL);
        return fresh;
    }

    public void invalidate(String caseId) {
        redis.delete("case:status:" + caseId);
    }
}

12.3 A concrete schema sketch

It helps to see actual table shapes rather than just names. Here is a simplified schema for the two most important tables, with comments explaining the reasoning behind each design choice.

CREATE TABLE cases (
    id                UUID PRIMARY KEY,
    order_id          UUID NOT NULL,
    buyer_id          UUID NOT NULL,
    seller_id         UUID NOT NULL,
    reason_code       VARCHAR(64) NOT NULL,
    status            VARCHAR(32) NOT NULL DEFAULT 'OPEN',
    order_value_cents BIGINT NOT NULL,
    currency          CHAR(3) NOT NULL,
    risk_score        NUMERIC(4,3),
    resolution_type   VARCHAR(32),
    resolution_reason TEXT,
    version           INTEGER NOT NULL DEFAULT 0,   -- optimistic locking, see 10.6
    evidence_deadline TIMESTAMPTZ NOT NULL,
    appeal_used       BOOLEAN NOT NULL DEFAULT FALSE,
    created_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at        TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Composite index supports the most common lookup pattern: "my open cases"
CREATE INDEX idx_cases_buyer_status ON cases (buyer_id, status);
CREATE INDEX idx_cases_seller_status ON cases (seller_id, status);

CREATE TABLE evidence_metadata (
    id             UUID PRIMARY KEY,
    case_id        UUID NOT NULL REFERENCES cases(id),
    uploader_id    UUID NOT NULL,
    object_key     TEXT NOT NULL,       -- pointer into S3, not the file itself
    content_type   VARCHAR(64) NOT NULL,
    size_bytes     BIGINT NOT NULL,
    scan_status    VARCHAR(16) NOT NULL DEFAULT 'PENDING_SCAN',
    superseded_by  UUID,                -- immutability: point to the newer record instead of overwriting
    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_evidence_case ON evidence_metadata (case_id);

Two details worth calling out: the version column exists purely to support the optimistic locking pattern from section 10.6, and object_key in evidence metadata is a pointer, never the file bytes themselves — the database only ever holds small, fast-to-query rows, while the expensive-to-move bytes stay in object storage. This split is what keeps the relational database small and fast even as total evidence volume grows into petabytes over the system’s lifetime.

12.4 Change Data Capture (CDC)

Rather than dual-writing to PostgreSQL and Elasticsearch (which risks the two falling out of sync), we use Debezium to stream row-level changes from PostgreSQL’s write-ahead log into Kafka, and consumers update Elasticsearch and the analytics warehouse from that stream. This keeps the primary write path simple (write to Postgres, done) while still feeding every downstream system.

Every microservice owns one responsibility and its own datastore, communicating only through APIs or events — never by reaching into another service’s tables directly.

13.1 Core API surface

13.2 Microservice boundaries

Each service owns exactly one responsibility and its own datastore, communicating with others only via well-defined APIs or events — never by reaching into another service’s database directly.

• Case Service — case lifecycle and state machine.
• Evidence Service — upload URL issuance, evidence metadata.
• Resolution Engine Service — rules + risk scoring + decision.
• Ledger Service — refunds, holds, payouts (financially isolated).
• Notification Service — push, email, SMS fan-out.
• Agent Queue Service — human review workflow.

13.3 Idempotency

Every write API (especially case creation and evidence upload confirmation) accepts an Idempotency-Key header. At a million requests a minute, client retries (due to timeouts, mobile network drops) are guaranteed to happen; without idempotency keys we’d risk duplicate cases or duplicate refunds.

@PostMapping("/v1/cases")
public ResponseEntity<CaseResponse> createCase(
        @RequestHeader("Idempotency-Key") String idempotencyKey,
        @RequestBody CreateCaseRequest request) {

    Optional<CaseResponse> existing = idempotencyStore.find(idempotencyKey);
    if (existing.isPresent()) {
        return ResponseEntity.status(HttpStatus.OK).body(existing.get());
    }

    CaseResponse created = caseService.createCase(request);
    idempotencyStore.save(idempotencyKey, created, Duration.ofHours(24));
    return ResponseEntity.status(HttpStatus.CREATED).body(created);
}

A million requests per minute (~16,700 RPS sustained, likely bursting to 40,000+ RPS at peak) is the design constraint that shapes almost every decision above. Let’s make the scaling levers explicit.

14.1 Where the load actually goes

Notice only a fraction of the million requests ever reaches a stateful write path. This is deliberate: CDN and cache absorb the majority, and only genuinely new writes touch the database tier.

14.2 Horizontal scaling of stateless services

Case Service, Evidence Service, and Resolution Engine are all stateless Java services running as Kubernetes Deployments with Horizontal Pod Autoscaling (HPA) based on CPU and request-queue-depth metrics. Because there’s no session affinity requirement, adding capacity is just adding pods behind the existing load balancer — no rebalancing needed.

14.3 Database scaling: sharding + read replicas

• Sharding spreads writes across N independent PostgreSQL clusters, each responsible for a slice of buyer IDs.
• Read replicas per shard absorb read traffic (case detail pages, agent search) without competing with write throughput.
• Connection pooling (PgBouncer) in front of every shard prevents connection exhaustion when hundreds of service pods each try to open direct connections.

14.4 Queue-based load leveling

Kafka partitions for case-events, evidence-events, and resolution-events are sized so that during a burst, producers (the fast, cheap part of the pipeline) never block on consumers (the Resolution Engine, which does heavier work like ML inference). The queue absorbs the burst; consumers catch up at their own sustainable rate. This is the single most important scale decision in the whole design — it converts a bursty, unpredictable inbound load into a smooth, controllable outbound processing rate.

14.5 Rate limiting and backpressure

The API Gateway enforces per-user and per-IP rate limits (token bucket algorithm) so a single abusive client can’t consume a disproportionate share of capacity. At the service level, bulkheads (separate thread pools per downstream dependency) stop a slow dependency, such as the ML scoring service, from starving unrelated request handling.

@Component
public class TokenBucketRateLimiter {

    private final RedisScript<Long> script = RedisScript.of(
        "local tokens = tonumber(redis.call('get', KEYS[1]) or ARGV[1]) " +
        "if tokens > 0 then " +
        "  redis.call('set', KEYS[1], tokens - 1, 'EX', ARGV[2]) " +
        "  return 1 " +
        "else " +
        "  return 0 " +
        "end", Long.class);

    private final StringRedisTemplate redis;

    public boolean allowRequest(String userId, int capacity, int windowSeconds) {
        Long result = redis.execute(script,
            List.of("rate:" + userId),
            String.valueOf(capacity), String.valueOf(windowSeconds));
        return result != null && result == 1L;
    }
}

14.6 Caching hot paths aggressively

Beyond case status, we cache: rules configuration (rarely changes, read on every decision), buyer/seller dispute-history aggregates (used by the risk model, refreshed every few minutes rather than computed per-request), and eligibility checks for common order types.

14.7 Capacity planning math

At 16,700 RPS sustained across roughly 8 stateless service pods per region per service, each pod handles about 2,100 RPS at low latency for simple JSON operations — well within what a well-tuned Java service on modern hardware can sustain, especially since most heavy lifting is deferred to async queue consumers. Multiplying pod count during peak (holiday season, flash sales) is a pure autoscaling exercise, not a redesign.

A dispute resolution system going down during a flash-sale return spike is almost as costly as the platform’s checkout going down — buyers panic, sellers panic, and support queues explode.

15.1 Multi-region active-active

Stateless services (Case, Evidence, Resolution) run active-active across at least two regions. Each region has its own database shards, replicated cross-region asynchronously for disaster recovery, but writes for a given user are always routed to their “home region” to avoid cross-region write conflicts.

15.2 Graceful degradation

15.3 Circuit breakers and retries

Every cross-service call (for example, Resolution Engine calling the ML Risk Scoring Service) is wrapped in a circuit breaker (Resilience4j). If the risk scoring service starts timing out, the breaker trips, and the Resolution Engine immediately falls back to “escalate to human” rather than piling up blocked threads.

@CircuitBreaker(name = "riskScoringService", fallbackMethod = "fallbackToEscalate")
public double score(CaseFacts facts) {
    return riskScoringClient.getScore(facts);
}

public double fallbackToEscalate(CaseFacts facts, Throwable t) {
    log.warn("Risk scoring unavailable for case {}, escalating to agent", facts.caseId());
    return 1.0; // treated as maximum risk, forces human review
}

15.4 Data durability

Evidence in object storage uses cross-region replication and versioning. Case and ledger databases use synchronous replication within a region (for zero data loss on a single-node failure) and asynchronous replication across regions (for disaster recovery within a defined RPO of a few seconds).

Because this system moves money and stores personal evidence, security is not one section — it’s a set of layered defenses baked into every service.

16.1 Authentication & authorization

All client requests carry a signed OAuth2/JWT token validated at the API Gateway. Authorization is enforced at the service layer too (defense in depth): a buyer can only read or comment on cases where they are a listed party, verified against the case record, not just trusted from the token.

16.2 Evidence security

• Pre-signed URLs expire in minutes and are scoped to a single object key, so they can’t be reused to upload arbitrary files elsewhere.
• Object storage buckets are private by default; evidence is served to clients only through short-lived signed GET URLs, never public links.
• All evidence is encrypted at rest (server-side encryption) and in transit (TLS 1.2+).

16.3 Fraud & abuse prevention

Beyond the ML risk score used in resolution, a separate abuse-detection layer watches for patterns like: the same device fingerprint opening disputes across many unrelated accounts, evidence photos that are reused across multiple unrelated cases (reverse image hashing), and velocity anomalies (a buyer suddenly filing 10 disputes in an hour).

16.4 PII and compliance

Evidence and case comments can contain personal data (addresses, phone numbers in chat logs). The system supports redaction on export, per-region data residency (EU case data stays in EU-hosted shards), and a “right to access / right to be forgotten” workflow that anonymizes closed cases past the legal retention period while preserving aggregate audit statistics.

16.5 Rate limiting against abuse

Beyond fairness rate limiting for scale (section 14.5), tighter limits specifically target abuse vectors: capping evidence uploads per case, capping appeal filings, and capping case creation per account per day to blunt refund-fraud rings.

You can’t run this system safely if you can’t see it clearly. Observability isn’t a nice-to-have here — it’s a prerequisite for automating money movement without a permanent human in the loop.

17.1 The three pillars

17.2 Business-level metrics

Beyond infrastructure health, the system tracks product-critical numbers: percentage of cases auto-resolved, average time-to-resolution by reason code, appeal rate (a proxy for resolution quality — a rising appeal rate suggests rules or the ML model need review), and agent queue depth versus SLA.

17.3 Alerting

Alerts are tiered: page an on-call engineer for consumer lag exceeding a hard threshold or error rate spikes; ticket (non-paging) for slower-moving signals like a creeping appeal rate. Every alert links directly to the relevant Grafana dashboard and runbook.

A well-designed architecture with a bad deployment story still ends up as a fragile production system. These are the deployment habits that pair well with the design above.

18.1 Containerized, orchestrated deployment

Every service ships as a Docker container and runs on Kubernetes, with separate node pools for latency-sensitive request-handling services versus batch-style workers (malware scanning, ML inference) that can tolerate more variable scheduling.

18.2 CI/CD pipeline

Code merges trigger automated tests, a container build, deployment to a staging environment running a shadow copy of production traffic, then a canary release (5% of production traffic) with automated rollback if error rate or latency regresses, before a full rollout.

18.3 Infrastructure as Code

All cloud resources (VPCs, Kubernetes clusters, database instances, IAM roles) are defined in Terraform, version-controlled, and reviewed like application code — this makes disaster recovery (“stand up an entire new region”) a repeatable, tested process rather than manual heroics.

18.4 Multi-cloud vs single-cloud consideration

Given the financial and trust-sensitive nature of this system, many marketplaces choose a single primary cloud provider with multi-region redundancy rather than full multi-cloud, since the operational complexity of multi-cloud rarely pays for itself compared to solid multi-region design — multi-cloud is usually reserved for specific regulatory requirements.

18.5 Cost optimization

At the volume this system targets, infrastructure cost becomes a design input, not an afterthought. A few concrete levers matter most:

• Object storage lifecycle tiers: Evidence older than 30 days with a closed, unappealed case moves to infrequent-access storage, and past the legal retention window moves to archival cold storage or is deleted, cutting storage cost dramatically since the vast majority of evidence is never looked at again after a case closes.
• Right-sized autoscaling floors: Rather than keeping peak-capacity pod counts running around the clock, minimum replica counts are set for off-peak hours (for example, overnight in a given region) with autoscaling handling the ramp back up before the next business day’s traffic arrives.
• Spot / preemptible instances for batch workers: Malware scanning and analytics batch jobs, which can tolerate being interrupted and retried, run on cheaper spot capacity, while latency-sensitive request-handling services stay on stable on-demand or reserved capacity.
• Selective use of serverless: Bursty, infrequent workloads like generating a monthly compliance export are a good fit for serverless functions billed per invocation, rather than paying for always-on capacity that sits idle most of the time.
• Cache-first reads: Every cache hit avoided a database read; at this scale, a well-tuned cache hit ratio of 90%+ on case-status reads directly translates into a proportionally smaller, cheaper database fleet.

A system that automatically decides refunds needs a testing strategy that goes well beyond typical unit tests, because the cost of a bug here is measured in real money and real trust, not just a failed request.

19.1 Layers of testing

• Unit tests on rule evaluation logic, state machine transitions, and idempotency handling, run on every commit.
• Contract tests between services (for example, Case Service and Resolution Engine agree on the exact shape of a case-created event) so a schema change in one service can’t silently break another at runtime.
• Shadow testing for new rules or a new ML model version: run the new logic against real production traffic in parallel with the live system, log what it would have decided, and compare against actual outcomes before ever letting it make a real decision.
• Chaos testing — deliberately killing pods, injecting latency into the risk-scoring call, or dropping a Kafka broker in a staging environment to verify the circuit breakers and fallback paths from section 15.3 actually work under real failure, not just in theory.
• Load testing — synthetic traffic generation (for example, using k6 or Gatling) ramped up to and beyond the million-requests-a-minute target, specifically watching for the first component to show backpressure, since that tells you where the next scaling investment needs to go.

19.2 Load test scenario example

A realistic load test doesn’t send uniform traffic — it models a flash-sale-triggered dispute spike: a sudden 5x jump in case creation over 10 minutes, sustained high evidence-upload volume, and a simultaneous burst of status-check polling from anxious buyers. The test asserts that p99 case-creation latency stays under 300 ms throughout, Kafka consumer lag returns to baseline within a defined recovery window after the spike ends, and no evidence uploads are lost or duplicated.

Patterns are the shorthand experienced architects use to communicate a whole design decision in two words. Anti-patterns are the shorthand for the mistakes those same architects have already made themselves at least once.

20.1 Patterns used

20.2 Anti-patterns to avoid

Every point in this section comes from the scars of a real production incident somewhere in the industry — either directly, or as an obvious extrapolation from one.

21.1 Best practices

• Always design the auto-resolution rate as a tunable dial, starting conservative and expanding automation coverage only as confidence in the data grows.
• Treat the audit log as a first-class, append-only, immutable data store — never let it be an afterthought bolted onto business logic.
• Version your API contracts and rules configuration; a rule change should be auditable exactly like a code change.
• Build a “dry run” mode for new rules — evaluate against real traffic without actually applying resolutions, and compare outcomes before enabling.
• Design for partial failure everywhere evidence, money, and notifications are involved; assume any single call can fail.

21.2 Common mistakes

• Underestimating evidence storage growth. Video evidence at scale can dwarf all other storage costs; plan lifecycle policies (cold storage, deletion after retention period) from day one.
• Ignoring appeal loops. Systems that don’t cap appeals or don’t flag repeat-appeal patterns can be gamed into infinite re-review cycles.
• Conflating case state with UI state. The backend case state machine should be the single source of truth; a common bug is letting the frontend infer status from disparate fields instead of one canonical status field.
• No fallback when automation dependencies fail. If the risk scoring service being down blocks case creation entirely instead of gracefully escalating, an outage in a “helper” service takes down the “core” feature.
• Treating the agent console as an afterthought. Because escalated cases are, by definition, the hardest and most ambiguous ones, giving agents a poorly designed queue with weak search and no context aggregation makes the highest-stakes decisions the ones made with the least support — invest in the agent-facing tooling at least as much as the buyer-facing one.
• Letting reason codes proliferate without governance. It’s tempting to let every team add a new reason code for their specific edge case, but an unbounded, poorly maintained taxonomy eventually makes both the rules engine and the analytics built on top of it unreliable; reason codes should go through the same review process as a schema change.
• Forgetting that automation decisions still need a human-readable explanation surfaced to the user. A buyer who receives “case denied” with no further detail is far more likely to escalate emotionally, contact support anyway, or leave negative reviews, even if the underlying decision was technically correct — the explanation is part of the product, not just an internal audit artifact.

Taken together, these mistakes share a common thread: they all treat some part of the system — the agent experience, the taxonomy, the explanation shown to users, the failure path — as secondary to the “real” engineering work of services and databases. In a system whose entire purpose is fairness and trust, there is no secondary part; every one of these details is load-bearing for the product’s actual goal.

Looking at how the largest marketplaces actually solve this problem is the fastest way to sanity-check your own design. Every one of them converges on the same broad shape.

22.1 What these platforms have in common

Looking across eBay, Amazon, PayPal, and Airbnb, the same underlying shape keeps appearing, which is a strong signal that this shape isn’t accidental but reflects real constraints every large marketplace eventually runs into.

This convergence is a useful sanity check when designing your own system: if your design is missing one of these five traits, it’s worth asking explicitly why — sometimes there’s a good reason specific to your product, but often it’s a gap that will surface painfully once real dispute volume arrives.

A quick reference for the terminology used throughout this tutorial, useful both for onboarding new engineers to the system and for interview prep.

If you were building this system from scratch inside an existing marketplace that currently only has manual, agent-driven dispute handling, a big-bang launch of the entire architecture described above would be unnecessarily risky. A more realistic path looks like this.

24.1 Stage 1: Structured intake, fully manual resolution

Replace free-text complaint forms with structured reason codes and a proper evidence-upload flow, but keep every single case routed to a human agent. This alone improves data quality and sets up everything else, while introducing zero automation risk.

24.2 Stage 2: Shadow automation

Run the rules engine and risk-scoring model in shadow mode: every case still goes to a human agent, but the system logs what it would have decided. Compare shadow decisions against actual agent decisions over weeks of real volume to measure accuracy before trusting the system with real money.

24.3 Stage 3: Limited auto-resolution

Turn on auto-resolution only for the narrowest, lowest-risk slice — for example, only for orders under a small dollar threshold with a specific reason code and a very low risk score — and closely monitor the appeal rate on that slice specifically.

24.4 Stage 4: Expand coverage gradually

Widen the rules’ scope and raise the risk-score threshold incrementally, each time observing appeal rate, agent queue relief, and any fraud signal before the next expansion, rather than jumping straight to broad automation.

24.5 Stage 5: Scale-out infrastructure

Only once the product behavior is proven and trusted does it make sense to invest in the full million-requests-a-minute infrastructure — sharding, multi-region deployment, and the complete event-driven pipeline — sized to the growth trajectory the business is actually seeing rather than a hypothetical peak.

The questions that come up over and over in interviews, architecture reviews, and Slack threads five minutes before a launch. Each answer traces back to a decision made earlier in this tutorial.

25.1 Key takeaways

What makes this system such a rewarding one to study, and to build, is that every architectural choice traces directly to a real, everyday human moment: a package that didn’t arrive, a listing that wasn’t what it looked like, a payment that never landed. The stateless services, the Kafka topics, the sharded databases, the risk-scoring gates — none of them exist for their own sake; they exist so that when Priya opens her case on a Tuesday afternoon, her refund arrives quickly, fairly, and with a clear explanation, and so that her seller, on the other side of the same case, is treated with the same fairness. Design reviews and interviews for this kind of system reward candidates who can hold both perspectives in mind simultaneously — the operational scale of a global platform, and the individual experience of a single frustrated user — and can show how each concrete architectural decision above serves both at once.

25.2 Where to go from here

If you are preparing this design for an interview, practice narrating it from the buyer’s POST all the way to the refund landing in their account, pausing at each hop to justify the specific technology choice with the specific requirement it serves — interviewers reward the candidate who can defend each decision with a concrete constraint rather than the one who lists the most fashionable technologies. If you are building this system for real, resist the temptation to skip straight to the fully-sharded, multi-region version on day one; a correct, observable single-region system with structured reason codes, an isolated ledger, and immutable evidence will teach you more about your actual dispute mix than any amount of premature scaling architecture ever could, and you will earn the right to add each subsequent layer precisely when real production data proves you need it.