Flipkart Marketplace Platform

Architecture Views

25 views, in reading order. Every view ships three ways: an HTML page, an SVG that re-opens in diagrams.net fully editable, and draw.io source.

Twenty-five views of a horizontal multi-vendor marketplace sized to the published Flipkart scale — 500M registered customers, 150M products, 1.4M sellers, 6M orders a day — built on open-source engines running on Azure managed infrastructure. Read it in seven acts: the boundary, the people, the structure, the data, the runtime, the operations, and the assurance. The architecture decision record below the index carries the reasoning for every component and every technology choice on these pages.

1 · Context and scope

What sits inside the boundary, who touches it from outside, and the shape of the whole thing in one picture.
01 Demand and content partners ONDC network Brand catalog feeds Ad and affiliate partners People Shopper 500M registered Seller 1.4M onboarded Care agent one order console Delivery partner hub and last mile Money and compliance UPI / NPCI collect + intent Cards, wallets, BNPL 3 acquirers routed Nodal settlement bank Flipkart Marketplace Platform 500M customers · 6M orders/day Supply, identity and messaging 3PL carriers 8 integrated KYC, GST and e-invoice PAN · GSTIN · IRP SMS / WhatsApp / push browse and buy list and ship resolve deliver authorise capture payouts catalog SKU master clicks manifest verify notify Flipkart Marketplace — System Context External / third party Person or role synchronous batch two-way event / async Everything inside the boundary is drawn from view 08 onwards. Warehousing robotics and the seller lending book are out of scope. v 1.0 · owner Enterprise Architecture · date 2026-09 System Context Who uses the marketplace, what it depends on, and what has deliberately been left outside the line. HTML page SVG draw.io
02 Edge Front Door + WAF Azure Front Door Media and CDN Blob + imgproxy Bot and rate limit Envoy + Redis Entry Customer BFF Envoy Gateway Seller and partner API API Management Identity Keycloak OIDC Discovery Catalog Cosmos DB NoSQL Search OpenSearch Recommendations KServe Pricing and offers Redis + rules Commerce Cart and checkout Java 21 Inventory Redis + Citus Order Citus shards Payments PCI enclave Backbone Event backbone Kafka / Strimzi Stream processing Flink Saga orchestration Temporal Fulfilment Fulfilment engine OR-Tools Logistics and last mile Notification fan-out workers Data and ML Lakehouse Iceberg on ADLS ML platform MLflow + KServe Trust and fraud Flink + models raw events index updates models High-Level Architecture — Edge to Data Platform Interface / broker Security / platform Application we own Queue / topic Data store event / async batch Read paths are cached at every hop; only inventory, payment and order state are read through to their systems of record. v 1.0 · owner Enterprise Architecture · date 2026-09 High-Level Architecture The shape of the platform in one picture, for the reader who will see only one. HTML page SVG draw.io

2 · People and journeys

Who the platform is for, what each of them gets to do, and the three journeys whose worst moments the rest of the set has to answer.
03 The people who buy Returning shopper 180M monthly active Goal — Buy the thing I already decided on, in under a minute, without losing my basket to a bank page. Core journeys Buy during a sale event 1.5M orders/hour peak Track a delivery Return and get refunded 6-8% of units First-time buyer tier-2 and tier-3, 3G Goal — Work out whether this seller is real before I pay anything, and pay cash if I am not sure. Core journeys Search and compare offers Place a COD order The people who sell Small seller 1.4M total, 90% long tail Goal — Get listed and paid without hiring anyone to operate a dashboard for me. Core journeys Onboard and pass KYC List, price and stock a SKU Get settled and reconciled T+7 cycle Brand or large seller top 2% by GMV Goal — Push a 200k-SKU catalog and a price change through an API and see it live everywhere within minutes. Core journeys Bulk catalog and price feed Run a sale campaign The people who run it Care agent one console, 11 languages Goal — Answer where is my order and issue the refund on one screen, without asking the customer twice. Core journeys Resolve an order query Issue a goodwill refund Trust and safety analyst marketplace governance Goal — Take a fraudulent seller off the platform before the orders they cannot fulfil are paid for. Core journeys Work a seller risk case Adjudicate a dispute On-call engineer follow the sun, 2 regions Goal — Know which of 400 services broke checkout before the conversion graph does. Core journeys Triage a peak-hour incident Shed load deliberately Partners and machines Delivery partner hub scan to doorstep Goal — Get a route I can finish before dark and a way to take cash that reconciles itself. Core journeys Run a last-mile route Remit COD collections 3PL carrier API 8 integrated Goal — Receive a manifest that loads without a human touching it, and post scans back at my own cadence. Core journeys Collect a despatch manifest Post a tracking scan Settlement run nightly, T+1 close Goal — Close the day so that every rupee taken, refunded and commissioned reconciles to the paisa. Core journeys Reconcile PSP and ledger Ranking retrain hourly features, daily model Goal — Refresh ranking and fraud models before the evening peak without touching the serving path. Core journeys Retrain and canary a model Actors and Their Core Journeys Person or role Journey / task External / third party Security / platform Volumes are the stated public scale plus a 10x sale-event multiplier. Machines with an SLA are actors here because otherwise they end up with no owner and no failure path. v 1.0 · owner Product + Enterprise Architecture · date 2026-09 Actors and Their Core Journeys Who this is for, and what each of them actually gets to do with it — including the machines that act without being asked. HTML page SVG draw.io
04 Returning shopper mobile-first, 180M MAU Goal — Get the deal I set an alarm for, before it sells out Trigger — A push notification at the top of the sale hour Done when — Order confirmed, unit reserved, payment captured once 1 · Notice push 2 · Find search 3 · Decide offers 4 · Reserve ◆ moment of truth 5 · Pay ◆ moment of truth 6 · Confirm What they do Taps the sale push Searches the model Filters by price Compares sellers Applies a coupon Adds to cart Hits Buy Now Chooses UPI Approves in bank app Sees the order Where Push FCM / APNs App search typeahead Product page Buy Box Cart server held UPI intent leaves the app Order tracker How it feels Delighted Fine Frustrated Behind the glass Campaign service Search and ranking Buy Box and pricing Inventory reserve Payment orchestrator Order and notify Where it hurts Queue page at 12:00 Price differs from list Oversold at checkout UPI app loses the cart Double debit, no order What would fix it Pre-warmed cache One price source Reserve before pay Server-side cart Idempotent capture How we know Open rate 14% p95 search 280 ms PDP p95 300 ms Oversell rate 0 Drop-off 11.4% Confirm p95 2 s User Journey — Shopper Buys During a Sale Event Reserve and Pay are the trough and the two moments of truth. Views 14 and 15 are the architectural answer to them. v 1.0 · owner Product + Enterprise Architecture · date 2026-09 Journey — Buying in a Sale Hour The journey that carries the most value and breaks in the most expensive place. Its trough is a structural requirement, not a UX complaint. HTML page SVG draw.io
05 Small seller long tail, 1.4M sellers Goal — Be listed, sell, and be paid, without a back office Trigger — Signing up with a PAN and a GSTIN on a phone Done when — Money in the bank on T+7, matching what the app said 1 · Onboard KYC 2 · List catalog 3 · Win Buy Box 4 · Ship ◆ moment of truth 5 · Get paid ◆ moment of truth 6 · Reconcile What they do Submits PAN, GSTIN Adds bank account Matches to a product Sets price and stock Watches the offer rank Packs and hands over Reads the payout Disputes a deduction Where Seller app OTP and documents Listing tool or bulk API Seller dashboard Pinot backed Manifest label and pickup Payout statement Dispute case How it feels Delighted Fine Frustrated Behind the glass Seller onboarding KYC and risk score Catalog moderation Buy Box scoring Fulfilment engine Settlement ledger Dispute workflow Where it hurts KYC stalls for days Rejected, no reason SLA breach, no warning Deduction unexplained What would fix it Async KYC with status Reason code on reject Show the Buy Box gap Predictive SLA alert Line-item statement Traceable ledger entry How we know KYC p50 4 h Live in 15 min Buy Box win rate SLA breach 1.8% T+7 on time 99.9% Dispute age p90 User Journey — Seller From First Listing to Settlement Settlement is the only phase where the platform holds the money of another business; the ledger behind it is why view 13 exists. v 1.0 · owner Product + Enterprise Architecture · date 2026-09 Journey — Seller, Listing to Settlement The supply side of the marketplace, from a phone-only signup to money in a bank account seven days later. HTML page SVG draw.io
06 Returning shopper 6-8% of units come back Goal — Send the wrong item back and get money, not a credit note Trigger — Opening a box that is damaged, wrong or not as described Done when — Refund on the original instrument, visible while it happens 1 · Raise in the app 2 · Pick up reverse leg 3 · Inspect ◆ moment of truth 4 · Refund ◆ moment of truth 5 · Recover who pays What they do Picks a reason Uploads a photo Hands to the rider Waits Checks the bank Where Returns flow app Rider app QR handover Return centre Refund status Seller dashboard How it feels Delighted Fine Frustrated Behind the glass Returns service Abuse scoring Reverse logistics Grading and restock Refund saga Claims and chargeback Where it hurts Pickup missed twice Silence for 5 days COD refund needs IFSC Seller charged unfairly What would fix it Instant refund if low risk Slot the pickup Push on each grade step UPI handle at checkout Evidence-linked claim How we know Return rate 6.8% Pickup SLA 92% Grade p50 36 h Refund p90 48 h Claim win rate User Journey — Return, Reverse Pickup and Refund The empty Recover cells are where the customer view ends, not a gap. Inspect is where trust is lost, and instant refunds trade money for retention. v 1.0 · owner Product + Enterprise Architecture · date 2026-09 Journey — Return and Refund The journey nobody designs for, which decides how much working capital the platform carries and who eats the loss. HTML page SVG draw.io

3 · Structure

The layers, the deployable units and every interface in and out. The engineering lead reads these three.
07 Experience Android app Kotlin iOS app Swift Mobile web React PWA Seller app React Care console Rider app offline first Edge and API Front Door + WAF Azure Front Door Customer BFF Envoy Gateway Partner API API Management Identity Keycloak Quota and bot defence Redis token bucket Discovery domain Catalog Search OpenSearch Recommendation Pricing Promotions Reviews Commerce domain Cart Checkout Inventory Order Payments PCI scoped Buy Box Seller, supply and trust Seller Fulfilment Logistics Returns Settlement Trust and fraud Platform services Event backbone Kafka Stream processing Flink Saga engine Temporal Cache and locks Redis Feature store Feast Notification Data and cloud foundation Sharded OLTP Citus PostgreSQL Catalog store Cosmos DB Search index OpenSearch Lakehouse Iceberg on ADLS Real-time OLAP Apache Pinot AKS + Istio Azure Kubernetes HTTPS / JSON OAuth2 client gRPC gRPC reserve raw topics sync read Layered Architecture — What Depends on What Application we own Interface / broker Security / platform Queue / topic Data store synchronous event / async failure / alternate Dependencies point down. The one red arrow is the exception the platform still carries: notification reads order state synchronously instead of consuming it. v 1.0 · owner Enterprise Architecture · date 2026-09 Layered Architecture What depends on what, and the one dependency that points the wrong way. HTML page SVG draw.io
08 Azure global edge Front Door Premium WAF + TLS 1.3 Static and media CDN Blob origin DDoS Protection network tier AKS — customer plane Entry Customer BFF Go 1.23 Keycloak OIDC + refresh Quota service Redis buckets Discovery Catalog API Java 21 Search API Go 1.23 Reco API KServe Pricing and offers Java 21 Commerce Cart Java 21 Checkout Java 21 Inventory Go 1.23 Order Java 21 AKS — PCI cardholder data environment (separate subscription) Payment orchestrator Java 21 Token vault HashiCorp Vault PSP connectors UPI · card · wallet Webhook receiver idempotent AKS — seller, supply and trust plane Seller Seller service Catalog ingest bulk feeds Settlement double entry Supply Fulfilment engine OR-Tools Logistics Returns Trust Risk scoring KServe Content moderation Dispute workflow Temporal Stateful platform on AKS Kafka Strimzi · 300 brokers Flink operator · 900 slots Temporal sagas OpenSearch 150M docs Apache Pinot seller analytics Azure managed data services Cosmos DB for PostgreSQL Citus · 64 shards Cosmos DB NoSQL catalog · multi-write Azure Managed Redis cart · locks · price ADLS Gen2 media + lakehouse Key Vault HSM keys UPI / NPCI Card acquirer 3PL carrier APIs KYC provider FCM / APNs / SMS HTTPS · Private Link OIDC introspect gRPC reserve mTLS · tokenised HTTPS SQL · shard key detokenise Container Architecture — Deployable Units and Their Stores Interface / broker Security / platform Application we own Queue / topic Data store External / third party synchronous One AKS fleet, four node-pool tenancies. Only the cardholder plane is a separate subscription and a separate cluster; everything else is namespace and mesh policy isolation. v 1.0 · owner Platform Engineering · date 2026-09 Container Architecture The deployable units, the technology each is written in, and the store each one owns. HTML page SVG draw.io
09 Inbound consumers Customer apps Seller portal and app Brand bulk feeds ONDC buyer apps Affiliate and ads Care and ops consoles Platform interfaces API Management OAuth2 · quotas Customer BFF Envoy Gateway Event backbone 38 topics · webhooks Outbound dependencies Payment rails UPI, cards, wallets Nodal bank payouts KYC and GST 3PL carriers REST REST bulk Beckn REST REST REST NACH REST scans Integration Architecture — Every Interface, Both Directions Application we own External / third party Interface / broker Queue / topic synchronous batch event / async SMS, WhatsApp and push providers are omitted here and drawn on the notification path. We own every contract except NPCI, the acquirer webhooks and the NACH file format. Each third-party call sits behind a circuit breaker with a stated fallback. v 1.0 · owner Integration Architecture · date 2026-09 Integration Catalogue Every way this platform touches another system, in both directions, with who owns the contract. HTML page SVG draw.io

4 · Data

Which store owns what, how data moves, what can be rebuilt, and the entities that make this a marketplace rather than a shop.
10 Systems of record — strongly consistent, never rebuilt from anything else Orders Citus · shard by order Payments and refunds Citus · PCI scope Inventory ledger Citus · append only Settlement ledger Citus · double entry Identity and consent PostgreSQL Authored masters — eventually consistent, owned by a person or a feed Catalog and listings Cosmos DB NoSQL Prices and promotions Cosmos DB + Redis Seller profile and KYC PostgreSQL + Blob Media and documents ADLS Gen2 Derived — rebuildable from the record or the log, so never backed up Search index OpenSearch · 150M docs Online features Feast on Redis Seller analytics Apache Pinot Read caches Redis · PDP, cart Analytical estate — the lakehouse Bronze · raw Raw topic landing Iceberg · 30 d Silver · conformed Conformed entities Iceberg · 3 y Gold · marts Business marts GMV, funnel, supply Training sets point in time Regulatory archive immutable · 8 y CDC · Debezium index rebuild upsert stream WORM export Data Architecture — Ownership and Rebuildability Data store event / async batch The classification decides the backup bill: only the top two boxes are backed up and point-in-time restorable. Everything in the derived box is rebuilt from Kafka or the record within an hour. v 1.0 · owner Data Architecture · date 2026-09 Data Architecture and Ownership Which store is the record, which is authored, which is derived — and therefore what has to be backed up. HTML page SVG draw.io
11 Sources App clickstream 4B events/day Domain events 38 topics OLTP change feed Debezium Partner feeds carriers, PSPs Ingest Kafka 7 d hot, tiered Schema registry Avro · compat gate Dead letter topics replayable Process Flink streaming exactly once Spark batch nightly restate Quality gates expectations Store Iceberg lakehouse bronze/silver/gold Pinot sub-second OLAP Feature store Feast online/offline Serve Trino ad hoc SQL Superset dashboards Metrics API seller and internal Model serving KServe Consume Sellers Analysts Ranking and fraud Finance and audit poison messages online features training sets Data Flow — Source to Decision Application we own External / third party Queue / topic Security / platform Data store Interface / broker Person or role failure / alternate event / async batch One log, two speeds. Flink computes what has to be right within seconds; Spark restates the same tables nightly so a late or corrected event never leaves the marts wrong. v 1.0 · owner Data Architecture · date 2026-09 Data Flow Where data comes from, what happens on the way, and who is allowed to consume it. HTML page SVG draw.io
12 Producer Topic Stream processing Consumers Materialised in Commerce Order service orders.v2 256 partitions Order state fan-out Flink Fulfilment, notify, care Order timeline Pinot Inventory Inventory service inventory.delta compacted Availability rollup Flink Search, PDP, Buy Box Availability cache Redis Payments Payment orchestrator payments.v1 PII redacted Settlement accrual Flink Order, settlement, risk Ledger entries Citus Catalog Catalog and pricing catalog.changes log compacted Enrich and embed Flink + AOAI Search indexer Search index OpenSearch Behaviour Apps and web clickstream.raw 4B/day Sessionise Flink Reco, ads, growth Feature store Feast Trust Every domain risk.signals Rules + model score Flink + KServe Case queue, blocks Risk decisions Citus Event Backbone — Who Publishes, Who Reacts Application we own Queue / topic Data store Security / platform Every topic carries a versioned Avro schema and an idempotency key. Compacted topics hold current state; append-only topics hold history and are the replay source for every derived store. v 1.0 · owner Platform Engineering · date 2026-09 Event Backbone Who publishes, what the topic guarantees, who reacts, and where the result is finally readable. HTML page SVG draw.io
13 customer customer_id PK phone_hash UQ tier created_at address address_id PK customer_id FK pincode geo_cell product product_id PK brand category_path attributes JSONB seller seller_id PK gstin UQ kyc_state risk_band order order_id PK customer_id FK state placed_at shard_key order_line line_id PK order_id FK listing_id FK qty unit_price listing listing_id PK product_id FK seller_id FK price buy_box_score inventory_ledger entry_id PK listing_id FK node_id delta reason payment payment_id PK order_id FK instrument psp_ref UQ state refund refund_id PK payment_id FK reason_code amount settlement_entry entry_id PK line_id FK type DR/CR amount cycle shipment shipment_id PK entry_id FK carrier tracking_ref state 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N 1 : N Core Data Model — Marketplace Entities listing is the join that makes this a marketplace: the same product carries many seller listings, and every commercial fact hangs off the listing, not the product. v 1.0 · owner Data Architecture · date 2026-09 Core Data Model The twelve entities that make this a marketplace rather than a shop, and the key that shards them. HTML page SVG draw.io

5 · Runtime

What actually happens when someone buys, when stock is contended, when an order fails, and when the item comes back.
14 Shopper Customer BFF Checkout Inventory Payment orch UPI / PSP Order Kafka 1. POST /checkout 2. create intent + idem key 3. reserve(listing, qty, ttl 900s) 4. Lua CAS on Redis counter 5. reservation_id 6. authorise(amount, idem key) 7. collect request 8. approve in bank app 9. webhook: authorised 10. dedupe on psp_ref 11. create order (Temporal saga) 12. confirm(reservation_id) 13. OrderCreated 14. order_id, ETA 15. confirmation screen 16. no webhook in 90 s 17. status poll, then void 18. release(reservation_id) Critical Flow — Reserve, Pay, Confirm Stock is reserved before money is asked for, and the reservation expires on its own. Every step carries the same idempotency key, so a retried webhook cannot create a second order or a second debit. v 1.0 · owner Commerce Engineering · date 2026-09 Checkout and Payment Sequence The one flow that must never take money without creating an order, or create an order without taking money. HTML page SVG draw.io
15 Available Redis counter Reserved TTL 900 s Confirmed ledger row written Allocated node and wave Fulfilled handover scan Reconciled count vs ledger One SKU at one node reserve · Lua CAS payment authorised fulfilment engine picks node picked and packed delivered, RTO or return drift correction, hourly Inventory — The Reservation Loop That Prevents Overselling Data store Application we own Opportunity Security / platform Expiry and cancellation return units to Available on the same path as reconciliation, so there is exactly one way stock comes back. v 1.0 · owner Commerce Engineering · date 2026-09 Inventory Reservation Lifecycle The hardest component in the marketplace, drawn as the loop it actually is. HTML page SVG draw.io
16 Capture CREATED PAYMENT_PENDING Authorise AUTHORISED PAYMENT_FAILED Commit CONFIRMED stock committed CANCELLED by buyer Prepare PACKED SELLER_CANCELLED SLA penalty Move SHIPPED OUT_FOR_DELIVERY RTO undeliverable Close DELIVERED RETURN_REQUESTED REFUNDED declined or timeout buyer cancels no stock at pick 3 attempts within window graded and accepted auto refund Order Lifecycle — States and Every Way Out Application we own Decision point Risk / gap Opportunity failure / alternate synchronous The Order service owns this machine and nothing else writes to it. Every red transition emits a compensating event; refunds and inventory releases are Temporal sagas, not in-line calls. v 1.0 · owner Commerce Engineering · date 2026-09 Order Lifecycle and Failure Paths The state machine the Order service owns, including every way out of it. HTML page SVG draw.io
17 Change capture Catalog changes compacted topic Price and offer Availability delta Enrich Attribute normalise Flink Embed title and image Azure OpenAI Listing quality score Index Bulk indexer p95 lag 30 s Lexical + kNN index OpenSearch Alias swap zero downtime Serve Query understanding spell, intent Retrieve BM25 + vector Rank KServe · 40 ms Buy Box choose price, SLA, rating Learn Clicks and buys Feature store Feast Train and register MLflow Canary and rollback 1% traffic promote model search Discovery Pipeline — Index, Retrieve, Rank, Learn Queue / topic Application we own Data store Security / platform Decision point batch synchronous Search never reads the catalog database. If the pipeline stops, the index serves stale-but-correct results and the availability filter is applied at query time from Redis. v 1.0 · owner Discovery Engineering · date 2026-09 Discovery Pipeline How 150M listings become a ranked page in under 300 ms, and how the ranking learns. HTML page SVG draw.io
18 Allocate Pick and pack First mile Line haul Last mile Proof Platform fulfilled Node selection OR-Tools Wave and pick WMS Sortation Own line haul Delivery hub route plan OTP or QR Seller fulfilled Seller node pincode serviceability Label and manifest Carrier pickup Carrier network 8 partners Carrier last mile Scan webhook signed Reverse Return authorised abuse score Reverse pickup slot Rider collects Return centre Grade and restock Refund trigger saga Promise and money Delivery promise ML ETA SLA clock starts Breach alerting Track and trace COD collection cash or UPI Remittance match T+2 Fulfilment — Three Supply Models, One Promise Application we own Security / platform Interface / broker External / third party Decision point The promise shown at checkout is computed from the same node-selection model that later allocates the order, so the ETA a shopper sees and the ETA operations plans against are one number. v 1.0 · owner Supply Chain Engineering · date 2026-09 Fulfilment and Last Mile Three supply models, one delivery promise, and the cash that has to come back. HTML page SVG draw.io

6 · Operations

Where it runs, how a change reaches production, how anyone knows it is working, and what is deliberately allowed to break at peak.
19 Global · Azure Front Door Premium (anycast, 190+ PoPs) Front Door + WAF latency routing Azure DNS health probes CDN cache media, static Azure Central India · primary, active Zone 1 AKS system + app 800 nodes Citus coordinators writer Kafka brokers 100 of 300 Zone 2 AKS app + spot 800 nodes Citus workers sync replica Kafka brokers 100 of 300 Zone 3 AKS app + GPU ranking, embed OpenSearch data 3 replicas Kafka brokers 100 of 300 Azure South India · secondary, read-active and failover Zone 1 AKS read plane 30% capacity Citus read replica async Zone 2 OpenSearch replica full index Kafka mirror MirrorMaker 2 Multi-region managed services Cosmos DB NoSQL multi-region write ADLS / Blob GZRS Key Vault paired region sync · RPO 0 async 30 s primary origin read spill Deployment — Regions, Zones and Failure Domains Interface / broker Security / platform Data store Queue / topic synchronous event / async RTO 20 min, RPO 30 s for the transactional tier; catalog and media are RPO 0 by construction. Regional failover is a rehearsed runbook with a human decision, not an automatic flip. v 1.0 · owner Platform Engineering · date 2026-09 Deployment Topology What runs where, what is redundant, and what a region loss actually costs. HTML page SVG draw.io
20 Source GitHub trunk + PR Review + CODEOWNERS Terraform modules infra as code Build GitHub Actions hermetic build SBOM + sign Syft · Cosign Container Registry Azure ACR Verify Unit + contract Pact SAST + secrets SonarQube Image + CVE scan Trivy Policy gate Kyverno Environments dev ephemeral staging prod-shaped data perf and game day 10x replay Release Argo CD GitOps sync Argo Rollouts canary 1-5-25% SLO gate auto rollback Sale freeze window code freeze Production AKS · 2 regions Feature flags kill switches Change audit who, what, when burn rate breach: roll back Delivery Pipeline — What Stops a Bad Change Application we own Decision point Security / platform Data store failure / alternate Nothing reaches production except by a signed image referenced from a Git commit. During a sale window the freeze is enforced by policy, and only flag flips and rollbacks are allowed. v 1.0 · owner Platform Engineering · date 2026-09 Delivery Pipeline and Environments How a change reaches production, and every gate that can stop a bad one. HTML page SVG draw.io
21 Emit Collect Store Consume Act Metrics OpenTelemetry SDK OTel Collector per node Prometheus + Thanos 13 mo Grafana SLO boards Page on burn rate multi-window Logs Structured JSON trace id bound Fluent Bit Loki 30 d hot Incident search Runbook link Traces OTel auto-instr 1% + tail sample OTel Collector Tempo 7 d Checkout latency Blame the hop service map Business Order and pay events Flink aggregates 10 s window Pinot GMV, conversion War room board sale day Page on conversion drop vs baseline Pipeline health Consumer lag Kafka exporter Prometheus Lag and DLQ board Auto scale consumers KEDA Cost Namespace tags OpenCost per service Cost mart Iceberg Unit cost per order Observability — Signal to Action Application we own Interface / broker Data store Security / platform Queue / topic The empty cell is deliberate: cost has no automated action, it has a monthly review. Business signal is treated as a first-class alerting source because conversion drops before CPU does. v 1.0 · owner SRE · date 2026-09 Observability and Operations How anyone knows it is working, and who gets woken up when it is not. HTML page SVG draw.io
22 Normal day 3x traffic 10x sale hour Brownout Search Full ranking p95 280 ms Scale replicas Cached top queries Lexical only no vector Product page Live price and stock Edge cache 30 s Edge cache 120 s Static shell + stock call Cart and checkout Full flow p95 500 ms Dedicated node pool Virtual waiting room fair queue Protected — never shed Payments All instruments PSP health routing Drop slow PSPs Protected — never shed Recommendations Personalised Shorter candidate set Precomputed segments Off Reviews and Q&A Live counts Cached counts Read only Off Seller analytics Near real time 60 s 5 min refresh Hourly refresh Yesterday only Notifications All classes Priority queue Transactional only Order and payment only Peak Load — What Must Work and What May Break Application we own Data store Decision point Interface / broker Security / platform Opportunity Risk / gap Queue / topic This table is the load-shedding contract, and it is enforced by feature flags rather than by judgement at 02:00. Yellow is a deliberate downgrade; red is switched off. v 1.0 · owner SRE + Product · date 2026-09 Peak Load and Graceful Degradation The load-shedding contract, agreed in advance so nobody has to invent it at 02:00. HTML page SVG draw.io

7 · Assurance

Where the trust boundaries are, who proves what to whom, and how the marketplace polices itself.
23 Untrusted · internet Shopper and seller Bots and account takeover scraping · stuffing Perimeter · Azure edge Front Door WAF OWASP + custom DDoS Protection network tier Bot defence device + behaviour Quota and throttle per token, per IP Application · private VNet, no public IP Envoy Gateway OIDC verify Keycloak MFA on risk Domain services Istio mTLS Authorisation OPA policy Cardholder data environment · separate subscription Payment orchestrator PCI DSS scope Token vault no PAN leaves Managed HSM keys never exported Data · restricted, private endpoints only Citus and Cosmos DB CMK at rest PII tokenisation phone, address Audit log WORM · 8 y HTTPS 443 challenged TLS mTLS + JWT tokens least priv audit Security Architecture — Trust Zones and What Crosses Them Person or role Risk / gap Security / platform Interface / broker Application we own Data store synchronous failure / alternate event / async No service holds a card number and no service reaches the internet directly; egress is through a firewall with an allow-list. Seller documents and customer PII are tokenised before they leave the owning service. v 1.0 · owner Security Architecture · date 2026-09 Security Zones Where the trust boundaries are, what crosses them, and where an attacker actually arrives. HTML page SVG draw.io
24 Shopper Mobile app Envoy Gateway Keycloak Risk engine Order service Policy engine Audit log 1. phone number 2. PKCE auth request 3. device, geo, velocity 4. risk score 5. OTP, step-up if risky 6. access 15 min + refresh 7. GET /orders + bearer 8. verify JWT, no introspect 9. mTLS + identity header 10. may this subject read? 11. allow, field mask 12. access record 13. orders, masked PII 14. refresh, rotate token 15. reuse detected: revoke family Identity — Who Proves What, To Whom, In What Order Customers, sellers and staff use three separate realms. Staff and seller staff federate to Microsoft Entra ID with conditional access; only the customer realm is Keycloak-native, and no realm shares a token audience. v 1.0 · owner Security Architecture · date 2026-09 Identity and Access Flow Who proves what, to whom, in what order — and what happens when a token is stolen. HTML page SVG draw.io
25 Signal Detect Decide Act Appeal Seller risk KYC, GSTIN, bank Cancel and SLA rate Risk band model KServe Auto or analyst band threshold Payout hold, delist Evidence upload SLA 72 h Buyer abuse Return and RTO rate Abuse score graph features Instant refund gate Inspect before refund Care override Payment fraud Device, velocity, BIN Real-time scoring Flink · 40 ms Allow, step-up, block 3DS or decline Chargeback defence Counterfeit and content Listing text and image Brand complaint Classifier + brand match Azure OpenAI Moderation queue Take down listing Seller counter-notice Review integrity Review burst pattern Ring detection graph clustering Confidence threshold Suppress and reweight Trust and Marketplace Governance — Signal to Enforcement External / third party Queue / topic Security / platform Decision point Application we own Person or role Every enforcement writes an immutable decision record with the model version and the features that fired, because an appeal that cannot be reconstructed is an appeal that will be lost. Review integrity has no appeal path by design: suppression is silent. v 1.0 · owner Trust and Safety Architecture · date 2026-09 Trust and Marketplace Governance How the marketplace polices itself, from a signal to an enforcement anyone can appeal. HTML page SVG draw.io

Architecture Decision Record

Why every component and every technology on these 25 views is what it is — and what each choice costs.

Twenty-eight decisions that are the architecture. Everything else on these twenty-five views is convention, and convention does not need defending. Each record states the forcing question, the choice, the credible alternatives with the reason each was rejected, and what the choice costs — because a decision recorded without its price is a decision nobody can revisit. The bias throughout is open-source engines running on Azure managed infrastructure: Azure is used where the managed service is genuinely better value at this scale, and an open-source engine is run on AKS where control over sharding, partitioning, retention or cost outweighs the operational burden.

Technology by capability

What each capability is built from, and the one-line reason. The record that argues each row is linked from it. Three records — ADR-16, ADR-17 and ADR-28 — decide behaviour rather than technology and so have no row here.

CapabilityBuilt withWhy this oneRecord
Global edge, WAF, CDN Azure Front Door Premium + DDoS Protection Anycast, TLS termination, WAF and caching in one managed hop; no origin has a public IP. ADR-01
Customer API entry Envoy Gateway on AKS Per-request cost at 10M+ RPS peak makes a per-call-priced gateway indefensible. ADR-03
Partner and seller API Azure API Management Subscription keys, quotas, versioning and a developer portal are the product, not the proxy. ADR-03
Compute substrate Azure Kubernetes Service One scheduler for 400 services, stateful engines and GPU inference; node-pool tenancy replaces cluster sprawl. ADR-02
Service-to-service security Istio ambient mesh mTLS and policy without a sidecar per pod, which at this pod count is a material cost line. ADR-04
Transactional core Azure Cosmos DB for PostgreSQL (Citus) Real SQL transactions that shard horizontally on order and seller keys. ADR-05
Catalog and listings Azure Cosmos DB for NoSQL Per-category document shapes, multi-region writes, and a read SLA the catalog path depends on. ADR-06
Inventory contention Redis (Azure Managed Redis) + Citus ledger An atomic Lua compare-and-set survives 100k concurrent buyers on one SKU; the ledger stays the truth. ADR-07
Search and vector retrieval OpenSearch on AKS 150M documents, hybrid BM25 and kNN in one cluster, with index lifecycle we control. ADR-08
Real-time analytics Apache Pinot Sub-second aggregation over upserted streams for seller dashboards and the sale-day war room. ADR-09
Lakehouse Apache Iceberg on ADLS Gen2, Spark, Trino, Airflow Open table format keeps the engine replaceable and the storage bill separable from the compute bill. ADR-10
Media Blob Storage + imgproxy behind the CDN Derivatives generated on demand and cached, so the origin holds one master per asset. ADR-11
Event backbone Apache Kafka on Strimzi Partition counts, compaction, tiered storage and quotas are all things this design must control. ADR-12
Stream processing Apache Flink Event-time windows, exactly-once sinks and real-time joins that Kafka Streams cannot carry alone. ADR-13
Long-running workflows Temporal Refunds, settlements and returns are month-long sagas needing durable state and visible retries. ADR-14
Change data capture Debezium into Kafka One log for the lake and the derived stores, with no dual writes to go out of step. ADR-15
Cart state Server-side, Redis-backed The basket has to survive the UPI handoff leaving the app entirely. ADR-18
Payments isolation Separate Azure subscription and AKS cluster + HashiCorp Vault token vault PCI scope stops at a subscription boundary; nothing else inherits the audit. ADR-19
Seller money Double-entry settlement ledger on Citus A payout dispute must be answerable from immutable entries, not from a mutable balance. ADR-20
Customer identity Keycloak on AKS Per-MAU identity pricing does not survive a 500M-user population. ADR-21
Workforce and seller-staff identity Microsoft Entra ID Conditional access, PIM and device compliance for every privileged human. ADR-21
Authorisation Open Policy Agent, policy as code Field-level masks reviewed as code rather than scattered through service handlers. ADR-22
Secrets and keys Azure Key Vault + Managed HSM, workload identity No secret in a manifest, and payment keys that never leave the module. ADR-19
Model serving KServe + MLflow + Feast on AKS Ranking, fraud and ETA models on the same fleet as the services that call them. ADR-23
Embeddings and moderation Azure OpenAI Elastic capacity for bursty catalog re-embedding without owning GPUs for the peak. ADR-24
Delivery GitHub Actions, Argo CD, Argo Rollouts, Kyverno, Terraform The cluster is reconciled to Git, so the audit trail and the rollback are the same mechanism. ADR-25
Observability OpenTelemetry, Prometheus + Thanos, Loki, Tempo, Grafana One vendor-neutral instrumentation layer, and retention priced as storage rather than as ingestion. ADR-26
Resilience Central India active, South India read-active Two in-country regions, honest RPO, and a failover that is rehearsed rather than assumed. ADR-27

The decisions, and the alternatives that lost

ADR-01

Terminate every request at Azure Front Door Premium

Edge Accepted
Context
Traffic is India-heavy but not India-only, arrives from mobile networks with poor last-mile latency, and multiplies roughly tenfold in a sale hour. The edge has to absorb volumetric attack, serve cached product and media bytes, and keep every origin off the public internet.
Decision
All ingress terminates at Front Door Premium with the managed WAF and network-tier DDoS Protection, and reaches AKS over Private Link. Static assets and product media are cached at the edge with short, explicitly set TTLs.
Options weighed
  • ChosenFront Door Premium — Anycast PoPs, WAF, caching and private origin in one product; the private-origin support is what removes the public IP.
  • RejectedApplication Gateway per region — Regional, so it needs Traffic Manager in front and gives no edge caching; two products to do one job.
  • RejectedThird-party CDN plus a self-run WAF — Better cache controls, but adds a vendor on the critical path and an egress bill between two clouds.
Consequences
What it buys
  • One place to shed load, block a botnet or serve a static maintenance page
  • Cache hit at the edge is the cheapest request the platform can serve
  • No workload has an internet-routable address
What it costs
  • Front Door is a single global control plane and therefore a systemic dependency
  • Cache purge is eventually consistent, so a price correction needs a versioned URL rather than a purge
  • WAF false positives on seller uploads need a tuned exclusion list
Shown on views 01 02 08 19 23
ADR-02

One AKS fleet with node-pool tenancy, not many clusters

Platform Accepted
Context
Roughly 400 services, several stateful engines (Kafka, Flink, OpenSearch, Pinot, Temporal) and GPU inference all need somewhere to run, with wildly different scaling behaviour and blast-radius requirements.
Decision
A single AKS fleet per region, partitioned by node pool and namespace: system, general application, spot-only batch, stateful, and GPU. The one exception is the cardholder data environment, which is a separate cluster in a separate subscription.
Options weighed
  • ChosenOne fleet, node-pool tenancy — One upgrade treadmill, one policy set, and bin-packing that a cluster-per-domain estate never achieves.
  • RejectedCluster per domain — Isolation is real but so is the cost: 20 control planes, 20 upgrade cycles and a mesh that has to span them.
  • RejectedAzure Container Apps — Excellent for the stateless tier and useless for Kafka, Flink and OpenSearch, which would need a second platform anyway.
Consequences
What it buys
  • Batch and stream work runs on spot capacity while checkout never does
  • One Kubernetes API to write policy, autoscaling and admission control against
  • GPU pools are shared across ranking, embedding and fraud rather than idling per team
What it costs
  • A cluster-wide failure is a regional failure; the control plane is the blast radius
  • Noisy-neighbour risk is managed by quota and priority classes, which needs continuous attention
  • Upgrades have to be choreographed across stateful workloads that dislike being drained
Shown on views 07 08 19 20
ADR-03

Two front doors: Envoy for customers, API Management for partners

Edge Accepted
Context
First-party apps generate the overwhelming majority of calls and need the cheapest possible per-request path. Sellers, brands, ONDC and affiliates need subscription keys, quotas, versioning, a developer portal and, eventually, monetisation — none of which the customer path needs.
Decision
Envoy Gateway on AKS is the customer BFF. Azure API Management fronts every partner and seller API. Both sit behind Front Door and both verify tokens locally.
Options weighed
  • ChosenEnvoy for first party, APIM for partners — Each surface pays for what it actually uses; consumption-priced gateways are confined to low-volume, high-governance traffic.
  • RejectedAPI Management for everything — Per-call pricing at peak volume is the single largest avoidable line in the estate.
  • RejectedEnvoy for everything — Would mean building a developer portal, key management and quota billing that APIM already ships.
Consequences
What it buys
  • Customer path latency and cost are controlled by us end to end
  • Partner governance, versioning and rate cards are configuration rather than code
  • A partner surge cannot exhaust customer gateway capacity
What it costs
  • Two policy surfaces to keep consistent on auth, CORS and rate limiting
  • Two sets of runbooks and dashboards
  • A shared concern such as a new auth scheme has to be implemented twice
Shown on views 02 08 09 24
ADR-04

Istio in ambient mode for mesh security

Platform Accepted
Context
Every service-to-service call must be mutually authenticated and encrypted, and traffic policy — retries, timeouts, circuit breaking, canary weights — should be uniform rather than reimplemented per language.
Decision
Istio ambient mesh across the fleet. mTLS and L4 policy come from the per-node ztunnel; L7 policy is added with a waypoint only for the services that need it.
Options weighed
  • ChosenIstio ambient — No sidecar per pod, so the memory and CPU tax scales with nodes rather than with pods.
  • RejectedIstio sidecars — Mature and well understood, but a sidecar on every pod at this pod count is a five-figure monthly line and a slower rollout.
  • RejectedLinkerd — Simpler and lighter, but the L7 policy and multi-cluster story here is weaker than what the trust boundaries need.
  • RejectedNo mesh, mTLS in libraries — Works until the fourth language arrives, then certificate rotation becomes everyone's problem.
Consequences
What it buys
  • Zero-trust between services without touching application code
  • Canary weights and circuit breakers are declarative and uniform
  • Certificate rotation is the platform's job
What it costs
  • Ambient mode is younger than sidecars; debugging tooling is still catching up
  • The ztunnel is a per-node dependency and a per-node failure domain
  • Waypoint proxies reintroduce a hop for services that need L7 policy
Shown on views 08 23
ADR-05

Citus on Azure Cosmos DB for PostgreSQL for the transactional core

Data Accepted
Context
Orders, payments, refunds, the inventory ledger and seller settlement need multi-row atomic transactions, foreign keys and the ability to answer a financial question exactly. They also need to hold 6M orders a day, and up to 1.5M in a peak hour, which no single PostgreSQL writer will do.
Decision
Azure Cosmos DB for PostgreSQL (managed Citus). Orders, order lines and payments are distributed on a key derived from order_id so an entire order is one shard and one local transaction; settlement is distributed by seller for the payout run.
Options weighed
  • ChosenCitus — Horizontal sharding with real PostgreSQL semantics, and the shard key can be chosen so that cross-shard transactions are rare.
  • RejectedSingle PostgreSQL Flexible Server — Correct and simple; the write ceiling arrives long before 6M orders a day.
  • RejectedCassandra or ScyllaDB — Scales beautifully and cannot give the atomic multi-row guarantee that a payment and its ledger entry require.
  • RejectedCosmos DB NoSQL for orders too — Transactions are limited to a logical partition, which forces the transaction boundary into application code for the one place it must not be.
Consequences
What it buys
  • Financial correctness is a database guarantee, not an application convention
  • Existing PostgreSQL skills, tooling, migrations and Debezium CDC all still apply
  • Read replicas and per-shard rebalancing are managed operations
What it costs
  • The shard key is close to irreversible; choosing it badly is the expensive mistake in this design
  • Cross-shard queries and joins are slow and must be designed out or served from the lakehouse
  • Cross-region replication is asynchronous, which is why the region-loss RPO is 30 seconds rather than zero
Shown on views 08 10 13 19
ADR-06

Cosmos DB for NoSQL as the catalog and listing store

Data Accepted
Context
150M products across categories whose attributes have nothing in common: a phone has storage and a colour, a shirt has a size and a fit, a book has an ISBN. Reads dominate by orders of magnitude and must be served in single-digit milliseconds from more than one region.
Decision
Cosmos DB for NoSQL holds products, listings and their attributes as documents, partitioned by category with a synthetic suffix on hot categories, and configured for multi-region writes with session consistency.
Options weighed
  • ChosenCosmos DB NoSQL — Schema-per-category without migrations, a read SLA the product page depends on, and multi-region writes out of the box.
  • RejectedMongoDB or Cassandra self-managed on AKS — Cheaper per gigabyte, and the operational load of a multi-region 150M-document cluster is a team we would rather spend elsewhere.
  • RejectedPostgreSQL with JSONB — Attractive for the smaller catalog it starts as, and the wrong shape by the time it is the real one.
Consequences
What it buys
  • A new category is a new document shape, not a schema migration
  • Multi-region writes make the catalog genuinely RPO 0
  • Throughput is provisioned per container, so a bulk feed cannot starve the product page
What it costs
  • Request-unit pricing rewards careful query design and punishes cross-partition scans
  • Partition-key choice is as consequential here as the shard key on Citus
  • Search and aggregation are somebody else's job — hence OpenSearch and Pinot
Shown on views 08 10 17
ADR-07

Redis as the inventory contention point, Citus as the truth

Commerce Accepted
Context
A sale item can have 100,000 people trying to buy the last few units in the same second. Overselling is unacceptable because it converts into a cancellation, a refund and a lost customer. Under-selling is also unacceptable because it is lost revenue on the item that drove the traffic.
Decision
Available stock per listing per node is a Redis integer. Reservation is a Lua script that checks and decrements atomically and writes a reservation with a 900-second TTL. Confirmation writes an immutable row to the inventory ledger in Citus. An hourly reconciliation corrects the counter from the ledger, never the other way round.
Options weighed
  • ChosenRedis atomic counter with a durable ledger — The contention point is an in-memory single-threaded operation; durability is provided by a store that is not on the hot path.
  • RejectedOptimistic concurrency in PostgreSQL — Correct and simple, and a single hot row with 100k contenders is a queue with a database attached.
  • RejectedDistributed locks — The lock would have to be held across a payment redirect measured in minutes, which is not a lock, it is an outage.
  • RejectedReserve nothing, oversell and cancel — Operationally cheapest and it makes the marketplace look broken exactly when the most people are watching.
Consequences
What it buys
  • Reservation p99 under 20 ms, with no lock and no database contention
  • Abandoned checkouts return stock automatically when the TTL expires
  • The ledger gives an auditable answer to where every unit went
What it costs
  • A Redis failover loses in-flight reservations; they are rebuilt from the reservation log with a brief oversell window
  • Reconciliation drift is a real, monitored business metric rather than a theoretical one
  • Seller stock also sold off-platform can never be perfectly accurate — SLA breach, not oversell, is the observable
Shown on views 04 08 14 15
ADR-08

Self-managed OpenSearch for lexical and vector retrieval

Discovery Accepted
Context
Search must cover 150M listings, answer in under 300 ms at p95, support faceting and typo tolerance, and increasingly handle semantic queries. Index freshness matters: a price change or a stock-out that is ten minutes stale produces a listing that cannot be bought.
Decision
OpenSearch on dedicated AKS node pools, holding both the lexical index and a kNN vector index over the same documents. Hybrid retrieval combines BM25 and vector scores; availability is applied as a query-time filter from Redis rather than being indexed.
Options weighed
  • ChosenOpenSearch self-managed — Apache-2.0, one cluster for both retrieval modes, and full control over sharding, refresh interval and index lifecycle.
  • RejectedAzure AI Search — Genuinely good and the per-partition pricing and index-size limits do not fit a 150M-document catalog with this churn.
  • RejectedElasticsearch — The stronger product in places; the SSPL licence is an unnecessary argument to have at this scale.
  • RejectedA separate vector database — Two systems to keep in sync over the same corpus, for a recall improvement that hybrid search in one cluster largely already provides.
Consequences
What it buys
  • One store, one query, one consistency story for both retrieval modes
  • Alias-based zero-downtime rebuilds make a bad index a pointer change to undo
  • Index freshness p95 of 30 seconds is achievable because we own the refresh policy
What it costs
  • A large stateful cluster to run, upgrade and capacity-plan — the biggest single operational burden in the estate
  • Vector indexes are memory-hungry, and embedding dimensionality is now a cost decision
  • Rebuild from Kafka takes about an hour, which is the real recovery time for a corrupted index
Shown on views 10 12 17
ADR-09

Apache Pinot for seller-facing and operational analytics

Data Accepted
Context
1.4M sellers each want their own near-real-time sales, funnel and SLA numbers, and the sale-day war room wants GMV, conversion and failure rates aggregated across the whole platform within seconds. Neither may touch the transactional shards.
Decision
Apache Pinot ingests from Kafka with upsert, serving both the seller dashboard API and the internal war-room boards.
Options weighed
  • ChosenApache Pinot — Built for exactly this: high-QPS, low-latency aggregation over a real-time stream with upsert semantics.
  • RejectedClickHouse — Faster on heavy analytical scans, weaker on the thousands-of-concurrent-tenants query pattern a seller dashboard actually is.
  • RejectedTrino over the lakehouse — Already in the estate for ad-hoc work; seconds-to-minutes latency is wrong for a dashboard a seller refreshes.
  • RejectedRead replicas of the transactional store — Puts analytical load next to the money path, which is the failure mode this whole separation exists to prevent.
Consequences
What it buys
  • Seller analytics stays under a second at high concurrency without touching Citus
  • Upsert handles order-state corrections without a rebuild
  • The same store serves the internal war room, so sellers and operations see one number
What it costs
  • Another stateful cluster with its own tuning discipline
  • Table and index design is per query pattern; a new dashboard is a schema conversation
  • Pinot has no mark in the icon library, so it carries a neutral store glyph on the views
Shown on views 10 11 12 21
ADR-10

Iceberg on ADLS Gen2 with Spark and Trino for the lakehouse

Data Accepted
Context
The analytical estate must hold years of clickstream, order and supply-chain history, feed model training with point-in-time correctness, answer finance and regulatory questions, and not lock the organisation into whichever engine is fashionable this year.
Decision
Apache Iceberg tables on ADLS Gen2 in a bronze/silver/gold layout. Spark on AKS for batch, Trino for interactive SQL, Airflow for orchestration, Superset for dashboards.
Options weighed
  • ChosenIceberg with Spark and Trino — Open table format with hidden partitioning, schema evolution and time travel; storage and compute are separately negotiable.
  • RejectedAzure Databricks with Delta — The best developer experience of the three and a per-DBU premium on a very large batch estate, plus a platform dependency.
  • RejectedMicrosoft Fabric or Synapse — Attractive integration; less control over file layout, compaction and cost at petabyte scale.
Consequences
What it buys
  • Time travel makes a wrong mart recoverable and a training set reproducible
  • Compute engines can be swapped without moving a byte of data
  • Bronze retention of 30 days keeps the largest tier cheap
What it costs
  • Compaction and small-file management are real jobs that must be scheduled and watched
  • A metastore is now a critical dependency of the analytical estate
  • Self-managed Spark is more operational work than a managed platform, and that is the price of the choice
Shown on views 10 11
ADR-11

One master per asset in Blob, derivatives generated on demand

Media Accepted
Context
Every listing carries several images, each needed in a dozen sizes and three formats across app, web and email. Pre-generating the full matrix for 150M listings is storage nobody should buy.
Decision
Sellers upload one master to Blob Storage. imgproxy on AKS generates the requested derivative on demand, signed by URL, and Front Door caches the result at the edge.
Options weighed
  • ChosenBlob plus imgproxy behind the CDN — One stored master, derivatives cached where they are consumed, and the transform is open-source and self-hosted.
  • RejectedPre-generate every variant — Simple and fast, and multiplies the storage bill by the size of the variant matrix, most of which is never requested.
  • RejectedA third-party image CDN — Excellent product, another vendor on the product-page critical path, and egress charged twice.
Consequences
What it buys
  • Storage grows with the catalog, not with the design system
  • A new breakpoint or format is a URL parameter, not a re-processing campaign
  • Signed URLs stop the transform service being used as free image processing
What it costs
  • A cold derivative costs a transform, so cache hit ratio is a business metric
  • The transform fleet has to be sized for the sale-hour cold-cache spike
  • Malicious or malformed uploads must be validated before they reach the transformer
Shown on views 02 08 10
ADR-12

Self-managed Kafka on Strimzi rather than Event Hubs

Eventing Accepted
Context
The event backbone carries around 4B clickstream events a day plus 38 domain topics, is the replay source for every derived store, and needs log compaction, tiered storage, per-tenant quotas and partition counts chosen per topic.
Decision
Apache Kafka on the Strimzi operator on AKS, roughly 300 brokers per region, tiered storage to Blob beyond seven days of hot retention, with MirrorMaker 2 replicating to the secondary region.
Options weighed
  • ChosenKafka on Strimzi — Full control of partitions, compaction, retention, quotas and tiering — every one of which this design depends on.
  • RejectedAzure Event Hubs (Kafka surface) — Removes the operational load and constrains partition counts, compaction and long retention in ways this backbone cannot accept.
  • RejectedApache Pulsar — Better tiered storage and multi-tenancy on paper; a much smaller operational talent pool to hire from.
  • RejectedAzure Service Bus — A queue, not a log. Replay is the whole point here.
Consequences
What it buys
  • Every derived store is rebuildable by replaying the log, which is what makes the no-backup policy defensible
  • Compacted topics give current state and append-only topics give history from the same infrastructure
  • Consumer autoscaling on lag rather than CPU, via KEDA
What it costs
  • A 300-broker fleet is a dedicated team with a permanent upgrade and rebalance workload
  • Partition count is easy to raise and impossible to lower without a topic migration
  • Cross-region mirroring lag is a leading indicator of a bad failover and needs its own alerting
Shown on views 02 08 11 12 19
ADR-13

Flink for stream processing, Spark for restatement

Eventing Accepted
Context
Availability rollups, fraud features, search index updates and settlement accruals must be computed within seconds of the event. The same numbers must also be correct after late-arriving and corrected events, which a streaming job alone cannot guarantee.
Decision
Apache Flink via the Kubernetes operator for all streaming computation, with event-time windows, checkpointing and transactional sinks. Spark restates the same gold tables nightly from the lakehouse.
Options weighed
  • ChosenFlink for streaming, Spark for batch restatement — Each engine used where it is strongest; the nightly restatement is the correctness backstop for the fast path.
  • RejectedKafka Streams only — Excellent for simple per-service transforms and weaker on large stateful joins and event-time semantics across domains.
  • RejectedSpark Structured Streaming only — One engine to operate, and micro-batch latency does not meet a 40 ms fraud-scoring budget.
Consequences
What it buys
  • Exactly-once end to end where it matters, at seconds of latency
  • One place to express event-time correctness rather than in each consumer
  • Late and corrected events cannot leave the marts permanently wrong
What it costs
  • Flink state backends and checkpointing need tuning, and a badly sized job fails at peak rather than in test
  • The same logic exists twice, in Flink and in Spark, and the two can drift
  • Savepoint-based upgrades are their own operational discipline
Shown on views 11 12 17 25
ADR-14

Temporal for sagas that span services and days

Commerce Accepted
Context
A refund touches the payment rail, the order, the inventory ledger, the seller claim and the settlement cycle, and can take weeks. A settlement run spans millions of entries and must be resumable. Pure choreography leaves this state implicit in a scattering of retry queues that nobody can inspect.
Decision
Temporal, self-hosted on AKS, orchestrates refunds, returns, settlement runs, dispute workflows and seller onboarding. Routine domain propagation stays choreographed over Kafka.
Options weighed
  • ChosenTemporal — Durable execution with visible history, so an operator can see exactly where a stuck refund stopped and why.
  • RejectedChoreography only — Fine for propagation and poor for compensation; the saga state ends up implicit and unqueryable.
  • RejectedAzure Durable Functions — Good managed option, and it pulls the money path onto a second compute platform with its own scaling behaviour.
  • RejectedLogic Apps — Integration-shaped rather than transaction-shaped; wrong tool for compensating financial workflows.
Consequences
What it buys
  • Compensation logic is code with tests, not a diagram in a wiki
  • Retries, timeouts and heartbeats come from the platform, uniformly
  • A stuck workflow is inspectable and resumable rather than lost
What it costs
  • Another stateful cluster with its own database and upgrade path
  • Workflow versioning is a genuine discipline — a long-running saga outlives several deployments
  • It is easy to over-apply; anything that fits an event is cheaper as an event
Shown on views 06 08 14 16 18
ADR-15

Debezium change data capture instead of dual writes

Data Accepted
Context
The lakehouse, the search index, the analytics store and the derived caches all need to know when a transactional row changes. Having each service publish its own event alongside its own write is the classic way to get the two permanently out of step.
Decision
Debezium reads the PostgreSQL write-ahead log and publishes change events to Kafka. Services publish business events for meaning; CDC publishes state for derivation. A transactional outbox is used where an event must be atomic with the write that caused it.
Options weighed
  • ChosenDebezium CDC plus an outbox where atomicity matters — The log is the single source; nothing can commit a row without the change being seen.
  • RejectedDual writes from the application — Two systems, no shared transaction, and eventual divergence with no way to detect it.
  • RejectedPeriodic batch extraction — Simple and it puts an hour of staleness in front of search and analytics, which is the whole problem.
Consequences
What it buys
  • No derived store can silently miss a change
  • Backfill is a connector snapshot rather than a bespoke migration
  • Business events stay about meaning rather than being overloaded with state
What it costs
  • Schema changes in the source now have downstream consumers, so migrations need an expand-and-contract discipline
  • Replication slots retain WAL, so a stalled connector becomes a database disk incident
  • Change events leak table shape, so a mapping layer is needed to keep it out of public contracts
Shown on views 10 11
ADR-16

Reserve stock before requesting money

Commerce Accepted
Context
UPI and card authorisation take the customer out of the app and can take a minute. Requesting money first and discovering afterwards that the unit is gone produces the most expensive failure the platform has: money taken, no order, and a refund to explain.
Decision
Checkout reserves inventory with a TTL, then requests payment, then confirms the reservation on authorisation. Any abandoned or failed path releases explicitly; TTL expiry is the backstop.
Options weighed
  • ChosenReserve, then pay, then confirm — Failure lands on stock, which is recoverable, rather than on money, which is not.
  • RejectedPay, then reserve — Maximises conversion on paper and converts every stock-out into a refund and a support contact.
  • RejectedNo reservation at all — Only defensible for genuinely unlimited stock, which a marketplace does not have.
Consequences
What it buys
  • A stock-out is discovered before the customer is charged
  • Reservation TTL puts a bound on how long abandoned baskets can hold inventory
  • The reservation identifier gives every downstream step something idempotent to key on
What it costs
  • Slow checkouts hold stock away from buyers who would have completed
  • TTL length is a tuned trade between conversion and availability, and it differs by category
  • A reservation service outage stops checkout even when stock exists
Shown on views 04 14 15
ADR-17

Buy Box as a scored, cached decision rather than cheapest-wins

Marketplace Accepted
Context
Many sellers offer the same product. Which offer a shopper sees decides the shopper's experience, the seller's revenue and the platform's fulfilment cost. Computing it per request over every listing is not affordable at product-page latency.
Decision
A Buy Box score per listing combines landed price, delivery promise, seller SLA history, return rate and stock position. It is recomputed on change events, cached in Redis, and read at page render.
Options weighed
  • ChosenPrecomputed multi-factor score — Fast to read, explainable to a seller, and it lets fulfilment reliability compete with price.
  • RejectedLowest price wins — Trivial to compute and it rewards sellers who cannot deliver, which the platform pays for later in cancellations.
  • RejectedScore at query time — Freshest possible answer and it does not fit inside a 300 ms product page across millions of listings.
Consequences
What it buys
  • Delivery reliability is a commercial incentive rather than a policy document
  • A seller can be shown why they lost the Buy Box, which is what makes the mechanism defensible
  • Product-page latency is unaffected by the number of competing offers
What it costs
  • The score is a ranking system, so it needs bias review and an appeal path
  • Score staleness during rapid price wars can show an offer that is no longer best
  • Weight changes move real revenue between sellers and must be governed, not tuned casually
Shown on views 04 13 17
ADR-18

Cart state lives on the server

Commerce Accepted
Context
The journey map is unambiguous: the deepest trough is payment, and the specific failure is a basket lost when the customer is sent to a UPI or bank application and comes back to a cold app. A client-held basket cannot survive that, nor a device switch.
Decision
Cart is a server-side entity keyed on customer identity, held in Redis with a durable write-behind, and returned intact on resume regardless of device or app restart.
Options weighed
  • ChosenServer-side cart — Survives the payment handoff, the device switch and the app crash — the three ways carts are actually lost.
  • RejectedClient-held basket — Zero infrastructure and it loses exactly the sessions worth the most money.
  • RejectedCookie or local storage with server merge — A merge strategy is a source of duplicate lines and support contacts, for a saving that does not matter.
Consequences
What it buys
  • Resume after a payment redirect is the default rather than a feature
  • Cart contents feed abandonment recovery and personalisation without client instrumentation
  • One cart across app, web and care console
What it costs
  • Cart is now a high-write service on the critical path with its own scaling profile
  • Anonymous-to-identified merge on login still has to be got right
  • Retention and privacy rules now apply to a store nobody thinks of as personal data
Shown on views 04 08 22
ADR-19

Isolate the cardholder data environment in its own subscription

Payments Accepted
Context
Card data brings PCI DSS scope, and scope is contagious: anything that can reach cardholder data is in the audit. With 400 services and hundreds of engineers, uncontrolled scope is both an audit cost and a permanent drag on delivery.
Decision
Payment orchestration, the token vault, PSP connectors and the webhook receiver run in a separate Azure subscription and a separate AKS cluster. The commerce plane holds only tokens and amounts, and reaches the boundary over mTLS. Payment keys live in a Managed HSM.
Options weighed
  • ChosenSeparate subscription and cluster — Scope stops at a subscription boundary that is also an RBAC, network and billing boundary.
  • RejectedNamespace isolation in the main cluster — Technically arguable, and it invites an auditor to ask about every workload sharing the control plane.
  • RejectedOutsource entirely to a PSP-hosted flow — Smallest possible scope and it surrenders routing across three acquirers, which is a real availability and cost lever.
Consequences
What it buys
  • The audit boundary is small, explicit and demonstrable
  • A compromise of the commerce plane yields tokens, not card numbers
  • Payment can be given its own change-control regime without slowing everything else
What it costs
  • A second cluster, a second pipeline and a cross-plane hop on the checkout path
  • Debugging spans a boundary that is deliberately hard to see across
  • Some duplication of platform capability inside the boundary
Shown on views 08 14 23
ADR-20

Double-entry settlement ledger, no mutable balances

Payments Accepted
Context
The platform holds other businesses' money between a customer payment and a seller payout, net of commission, shipping, penalties and refunds. A seller who disputes a deduction must be given a traceable answer, and finance must reconcile to the paisa against PSP statements.
Decision
Settlement is an append-only double-entry ledger in Citus, one entry pair per commercial fact, keyed to the order line that caused it. Balances are projections. PSP statements are reconciled against the ledger daily, and financial records are exported write-once for eight years.
Options weighed
  • ChosenAppend-only double-entry ledger — Every rupee has two sides and a cause; a dispute is answered by replaying entries.
  • RejectedMutable balance column per seller — Simple, fast and unanswerable the first time a seller asks why a number moved.
  • RejectedReconstruct from order events on demand — Correct in principle, and it makes finance depend on the event retention policy of another team.
Consequences
What it buys
  • Any payout can be explained line by line back to an order line
  • Reconciliation breaks are detected daily instead of at quarter end
  • The audit and regulatory export is a read of an immutable table
What it costs
  • The ledger is the fastest-growing transactional table in the estate
  • Corrections are reversing entries, never edits, which people find unintuitive
  • Projection lag means a seller-facing balance is a near-real-time number, not an instantaneous one
Shown on views 05 10 13 18
ADR-21

Keycloak for 500M customers, Entra ID for every privileged human

Identity Accepted
Context
Customer identity is a very large, low-value-per-identity population authenticating mostly by phone and OTP. Staff and seller-staff identity is a small, high-value population that needs conditional access, privileged access management and device compliance.
Decision
Keycloak, self-hosted on AKS, is the customer realm. Microsoft Entra ID is the workforce and seller-staff realm. Three realms, three token audiences, no shared tokens.
Options weighed
  • ChosenKeycloak for customers, Entra ID for workforce — Each population served by the system whose pricing and feature model fits it.
  • RejectedEntra External ID for customers too — One vendor and one operating model; per-monthly-active-user pricing at 180M actives is not defensible.
  • RejectedBuild it in house — Nobody should implement OIDC, token rotation and MFA from scratch in 2026.
Consequences
What it buys
  • Identity cost scales with infrastructure rather than with population
  • Privileged access keeps enterprise-grade conditional access and PIM
  • A stolen seller token cannot be replayed against a customer API
What it costs
  • A highly available Keycloak cluster with an upgrade treadmill and an owning team
  • Two identity operating models, two sets of runbooks
  • Federation between the realms has to be designed rather than assumed
Shown on views 08 23 24
ADR-22

Authorisation as policy code with field-level masks

Security Accepted
Context
The same order endpoint is called by the customer who placed it, a care agent, a seller who fulfils one line of it and an internal analytics job. Each is entitled to a different subset of the same record, and encoding that in handler code guarantees it drifts.
Decision
Open Policy Agent evaluates authorisation next to each service. The decision returns both an allow or deny and a field mask, so one endpoint serves every caller at the right level of detail.
Options weighed
  • ChosenPolicy as code with field masks — Access rules are reviewable, testable and diffable in one place.
  • RejectedChecks in application code — Works for three roles and becomes untraceable at thirty.
  • RejectedSeparate endpoints per audience — Explicit and it multiplies the API surface and the ways it can drift apart.
Consequences
What it buys
  • One place to answer who can see a customer's phone number
  • Policy changes ship without changing service code
  • The decision is loggable, so an access review has data to work from
What it costs
  • Policy evaluation is on the request path and has a latency budget
  • Policy is a language engineers must learn, and a bad policy fails closed at peak
  • Masks must be tested, or a field quietly disappears from a response
Shown on views 23 24
ADR-23

KServe, MLflow and Feast on the same fleet as the callers

ML Accepted
Context
Ranking, recommendation, fraud scoring, delivery-time prediction and abuse detection are all on request paths with millisecond budgets. Training is bursty and offline. Training and serving must see the same features or the models silently decay.
Decision
MLflow as the registry, Feast as the feature store with Redis online and Iceberg offline, KServe for serving on the same AKS fleet, with canary rollout and automatic rollback on latency or quality regression.
Options weighed
  • ChosenKServe, MLflow and Feast on AKS — Inference is a pod next to the caller, so there is no cross-boundary hop inside a 40 ms budget.
  • RejectedAzure Machine Learning managed endpoints — Less to operate, and a network hop and a scaling model outside our control on the request path.
  • RejectedModels embedded in each service — Lowest latency of all and no shared versioning, rollback or monitoring — every team reinvents deployment.
Consequences
What it buys
  • One feature definition serves training and inference, which removes the commonest cause of silent decay
  • Model rollout uses the same canary and rollback machinery as service code
  • GPU pools are shared across ranking, embedding and fraud
What it costs
  • Three more open-source components to run and upgrade
  • Feature-store correctness at point in time is subtle and easy to get wrong
  • Canary catches latency regressions but not slow relevance decay, so a human review stays in the loop
Shown on views 11 17 25
ADR-24

Azure OpenAI for embeddings and content moderation

ML Accepted
Context
Semantic search and counterfeit detection need text and image embeddings over a catalog that churns in bursts — a brand re-uploading 200,000 listings is a single event. Owning GPU capacity for that peak means owning idle GPUs the rest of the time.
Decision
Azure OpenAI provides embeddings for catalog text and images and first-pass moderation classification, called from Flink enrichment jobs rather than from any request path. Embeddings are cached and only recomputed when the source text changes.
Options weighed
  • ChosenAzure OpenAI — Elastic capacity for a bursty workload, inside the same tenancy and data-residency boundary.
  • RejectedSelf-hosted open-weight embedding models — Cheaper per token at steady state and it requires provisioning for the burst, which is the whole difficulty.
  • RejectedNo semantic layer at all — Lexical search alone loses long-tail and vernacular queries, which is a large share of Indian e-commerce search.
Consequences
What it buys
  • No GPU fleet sized for a re-upload spike
  • Model upgrades are a version change, not a migration
  • Cost tracks catalog churn, which is measurable and controllable
What it costs
  • A managed dependency in the indexing path, so quota and throttling are capacity-planning inputs
  • Changing embedding model means reindexing the whole corpus
  • Nothing on a customer request path may call it — that is a rule, not a guideline
Shown on views 12 17 25
ADR-25

GitOps with Argo CD, and progressive delivery with automatic rollback

Delivery Accepted
Context
Hundreds of engineers deploying to a fleet running the country's shopping traffic need a change mechanism that is auditable, reversible and unable to be bypassed under pressure.
Decision
Git is the only way in. Argo CD reconciles the cluster to the repository, Argo Rollouts runs canaries at 1, 5 and 25 percent gated on SLO burn rate, and Kyverno rejects any image that is unsigned or lacks an SBOM. Terraform owns the infrastructure.
Options weighed
  • ChosenGitOps with progressive delivery — The audit trail and the rollback are the same mechanism, which is what makes it hold up under pressure.
  • RejectedPipeline-push deployment — Familiar, and cluster state drifts from any repository as soon as someone is in a hurry.
  • RejectedManual approval gates only — A human approving a change they cannot evaluate is a ritual, not a control.
Consequences
What it buys
  • Rollback is a revert, and it works at three in the morning
  • Every production change has an author, a reviewer and a commit
  • Drift is detected and corrected continuously
What it costs
  • Database migrations are the one class GitOps does not make safe; expand-and-contract is mandatory
  • Feature flags accumulate into untested branches unless they are actively retired
  • The freeze window during sale events shifts risk to the release immediately after it
Shown on views 20
ADR-26

OpenTelemetry with an open-source backend per signal

Operations Accepted
Context
Four hundred services in several languages must be observable at a volume where per-gigabyte ingestion pricing becomes a governing constraint on what can be measured. And the earliest signal that checkout is broken is not a machine metric — it is conversion.
Decision
OpenTelemetry instrumentation everywhere, collected by the OTel Collector, stored in Prometheus with Thanos for metrics, Loki for logs and Tempo for traces, and presented in Grafana. Business metrics from Flink into Pinot are a first-class alerting source. Azure Monitor covers the platform plane only.
Options weighed
  • ChosenOpenTelemetry with the open-source stack — Vendor-neutral instrumentation, retention priced as object storage, and thirteen months of history for year-on-year sale comparison.
  • RejectedAzure Monitor and Application Insights throughout — Excellent integration and an ingestion bill at this event volume that would force sampling decisions for the wrong reason.
  • RejectedA commercial observability platform — Best product experience of the three, and per-host and per-gigabyte pricing across this fleet is not affordable.
Consequences
What it buys
  • Instrumentation is portable, so the backend stays replaceable
  • Long metric retention is affordable, which is what makes sale-on-sale comparison possible
  • Conversion drops page before CPU does
What it costs
  • Four storage systems to operate, scale and upgrade
  • Tail-based sampling needs tuning, and a bad rule loses the traces that mattered
  • Correlation across the four backends is Grafana's job and needs deliberate dashboard design
Shown on views 21 22
ADR-27

Two Indian regions, active and read-active, with an honest RPO

Resilience Accepted
Context
Data residency keeps everything in India, which leaves two Azure regions. The customer-facing availability target is 99.99%. Genuine active-active writes on a sharded relational core across regions would mean either synchronous cross-region commits or conflict resolution on financial data.
Decision
Central India is the active write region across three availability zones with synchronous in-region replication. South India is read-active at about 30% capacity with asynchronous replication, a full search index replica and a mirrored Kafka. Regional failover is a rehearsed runbook with a human decision point.
Options weighed
  • ChosenActive primary, read-active secondary — Zone loss is invisible; region loss is a 20-minute rehearsed procedure with a stated, honest 30-second data loss.
  • RejectedActive-active writes across both regions — Either synchronous commits across regions, which breaks the checkout latency budget, or conflict resolution on money, which nobody should build.
  • RejectedSingle region, three zones — Cheapest and simplest, and it has no answer at all to losing a region.
Consequences
What it buys
  • Zone failure is handled by the platform with RPO 0
  • Read traffic can spill to the secondary during a peak, so the standby capacity is not idle
  • Catalog and media are genuinely multi-region by construction
What it costs
  • Up to 30 seconds of transactional writes lost in a region failover, reconciled by a manual playbook
  • Standby capacity is a permanent cost against an event that may never happen
  • Failover must be rehearsed quarterly or the runbook is fiction
Shown on views 19 22
ADR-28

A written degradation contract enforced by feature flags

Resilience Accepted
Context
In a sale hour traffic multiplies tenfold and something has to give. Deciding what gives while it is happening produces inconsistent, unrehearsed and occasionally revenue-destroying choices.
Decision
Every customer-facing capability has a written behaviour at normal, 3x, 10x and brownout load. Cart, checkout and payment are protected and never shed. Each cell is a feature flag with a named owner, exercised in a game day before every sale event.
Options weighed
  • ChosenA pre-agreed contract behind flags — The decision is made calmly, in advance, by the people who own the revenue it affects.
  • RejectedAutoscale and hope — Autoscaling has a lead time and a quota ceiling; both are discovered at exactly the wrong moment.
  • RejectedShed at the load balancer — Sheds randomly, which means it sheds paying customers as readily as browsers.
Consequences
What it buys
  • Nobody improvises during the highest-revenue hour of the year
  • Product owners have agreed in advance what their feature does under stress
  • Game days prove the flags work rather than assuming they do
What it costs
  • Degradations interact: a cached price plus a stale availability filter can show an offer that cannot be bought
  • The waiting room is the most visible mechanism in the set — if it misbehaves, it becomes the story
  • Above roughly 5x the binding constraint is physical fulfilment capacity, which no flag can relieve
Shown on views 03 21 22
Open svg/<view>.svg or drawio/<view>.drawio in draw.io Desktop or at app.diagrams.net to edit. The SVG carries the diagram inside it, so it is both the picture and the source. This folder is self-contained — copy it whole and every link still resolves.
Solution Architecture v1.0 · Open source on Microsoft Azure · Enterprise Architecture · 2026-0925 views · HTML / SVG / draw.io