# Flipkart Marketplace Platform

**Solution Architecture v1.0 · Enterprise Architecture · 2026-09 · 25 views · Open source on Microsoft Azure**

A horizontal multi-vendor marketplace sized to the published Flipkart scale — 500M registered customers, 150M products, 1.4M sellers, 6M orders a day, and sale events assumed at ten times the daily average concentrated into a few hours. Eight decisions carry the design: stock is reserved before money is requested, so a failure lands on inventory rather than on a payment; inventory contention is settled by an atomic Redis compare-and-set with an append-only ledger behind it, because 100,000 buyers on one SKU is a queue with a database attached in any other design; the transactional core is sharded PostgreSQL (Citus) because financial correctness has to be a database guarantee rather than an application convention; cart lives on the server, because the deepest trough on the shopper journey is a basket lost to a UPI redirect; the cardholder data environment is a separate Azure subscription, so PCI scope stops at a boundary that is also an RBAC, network and billing boundary; the event backbone is self-managed Kafka, because every derived store in the estate is rebuilt by replaying it and none of them are backed up; the Buy Box is a precomputed multi-factor score, so delivery reliability competes with price; and what degrades at ten times traffic is a written contract behind feature flags, agreed before the sale rather than invented during it.

Twenty-eight architecture decision records carry the reasoning for every component and every technology on these views, with the alternatives that lost and what each choice costs. They are rendered on the landing page of the diagram set, directly below the index, and again as [docs/adr.md](docs/adr.md).

---

## What is here

| Path | Contents |
|---|---|
| `diagrams/index.html` | The landing page — 25 views grouped into seven acts, every format linked, and the full architecture decision record below the index |
| `diagrams/*.html` | One self-contained page per view: the inlined diagram plus the reasoning it deliberately omits, with copy / PNG / PDF export |
| `diagrams/svg/*.svg` | The same 25 views as SVG with the diagram XML embedded — re-opens in diagrams.net fully editable |
| `diagrams/drawio/*.drawio` | draw.io native source |
| `docs/adr.md` | The architecture decision record as markdown |
| `specs/views.json` | Diagram specifications — the source of truth for every view (assembled from `part-a..g.json`) |
| `specs/manifest.json` | Acts, page titles, subtitles and the decision / assumption / risk cards (assembled from `manifest-a..b.json`) |
| `specs/adr.json` | The 28 decision records and the capability-to-technology table |
| `scripts/build.sh` | Rebuilds every deliverable from the specs |
| `scripts/pin-icons.mjs` | Pins one mark per component, and stops the resolver putting another product's logo on a box |
| `scripts/render-adr.mjs` | Renders `adr.json` into `diagrams/index.html` and `docs/adr.md` |
| `ask.md` | The original requirement |

Every component carries its own mark — 601 icons embedded in the files, so the deliverable renders identically anywhere with no external requests. Each view page links to its own SVG and draw.io source, back to the index, and to the previous and next view.

To rebuild after editing a spec:

```bash
bash scripts/build.sh          # requires Node 20+ and nothing else
```

Edit `specs/part-a.json` … `part-g.json`, `specs/manifest-a.json` / `manifest-b.json` and `specs/adr.json`; the build script assembles `views.json` and `manifest.json` from them, pins the icons, then generates, validates, route-checks, renders, link-checks and injects the decision record in one pass.

---

## The seven acts

| Act | What it lands | Views |
|---|---|---|
| 1 · Context and scope | The boundary, who touches it, and the shape of the whole platform in one picture | 01–02 |
| 2 · People and journeys | Buyers, sellers, operators and machines — and the three journeys whose worst moments the rest of the set answers | 03–06 |
| 3 · Structure | The layering rule, the deployable units and every interface in and out | 07–09 |
| 4 · Data | Which store owns what, what is rebuildable, how data moves, and the entities that make this a marketplace | 10–13 |
| 5 · Runtime | Reserve-pay-confirm, the inventory loop, the order state machine, discovery, and fulfilment | 14–18 |
| 6 · Operations | Regions and failure domains, delivery, observability, and the degradation contract | 19–22 |
| 7 · Assurance | Trust zones, identity, and how the marketplace polices itself | 23–25 |

---

## The views

| # | View | What it answers |
|---|---|---|
| 01 | System Context | Who uses the marketplace, what it depends on, what is out of scope |
| 02 | High-Level Architecture | The shape of the platform in one picture |
| 03 | Actors and Their Core Journeys | Who it is for and what each of them gets to do, machines included |
| 04 | Journey — Buying in a Sale Hour | Where the highest-value journey breaks, and what that decides |
| 05 | Journey — Seller, Listing to Settlement | The supply side, from phone-only signup to money in the bank |
| 06 | Journey — Return and Refund | Who eats the loss, and how much working capital it costs |
| 07 | Layered Architecture | What depends on what, and the one dependency pointing the wrong way |
| 08 | Container Architecture | The deployable units, their technology, and the store each owns |
| 09 | Integration Catalogue | Every interface in and out, and who owns the contract |
| 10 | Data Architecture and Ownership | Record, authored, derived — and therefore what gets backed up |
| 11 | Data Flow | Source to decision, at two speeds |
| 12 | Event Backbone | Who publishes, who reacts, and where the result becomes readable |
| 13 | Core Data Model | The twelve entities, and the listing that makes it a marketplace |
| 14 | Checkout and Payment Sequence | Reserve, pay, confirm — and every way out of it |
| 15 | Inventory Reservation Lifecycle | How overselling is prevented under extreme contention |
| 16 | Order Lifecycle and Failure Paths | The state machine, including the failure states |
| 17 | Discovery Pipeline | Index, retrieve, rank, learn — in under 300 ms |
| 18 | Fulfilment and Last Mile | Three supply models, one promise, and the cash coming back |
| 19 | Deployment Topology | What runs where, and what a region loss actually costs |
| 20 | Delivery Pipeline and Environments | How a change reaches production and what stops a bad one |
| 21 | Observability and Operations | How anyone knows it is working, and who gets woken up |
| 22 | Peak Load and Graceful Degradation | What must work, what may break, and who agreed |
| 23 | Security Zones | Where the trust boundaries are and where an attacker arrives |
| 24 | Identity and Access Flow | Who proves what to whom, and what happens to a stolen token |
| 25 | Trust and Marketplace Governance | Signal to enforcement, with an appeal that can be reconstructed |

---

## Build state

- `validate.mjs --strict`: 25 files, **0 errors, 0 warnings**
- `route-check.mjs`: 198 edges routed, **0 errors**, 2 accepted clutter warnings on view 09, where two outbound interface labels sit close together and dropping an interface would misrepresent the estate
- `icons.mjs check`: 563 nodes, **0 unresolved, 0 weak matches**
- `check-links.mjs`: 26 pages, every relative link resolves — the folder is self-contained