06 · A cart where stock changes while you shop

• Repository — the one owner of one kind of data. It turns the server's format into the app's model.
• Composite — a repository that only reads: it asks two repositories and combines their answers into one model. Not needed here.
• Store — in-memory state that several screens show at once. Here: the cart.
• Use case — one user intent with a product rule, like "only the latest tap counts".
• View model — the screen's brain. It owns the screen's state and hands the screen one view state.
• Hub — the small local warehouse serving an address, with its own stock and cart.
• Adjustment — a change the server made to a line on its own: out of stock, fewer left, a new price.
• Deposit (Pfand) — a refundable charge on bottles and cans, added per item.
• Idempotency key — a random ID on a request, so the server can tell a retry from a new one.
• 3-D Secure — the bank's extra check for card payments, often in its own app.

"Where does the cart live?" → On the server, one per user per hub. It follows the user to their iPad.

"Who computes prices, deposit and fees?" → The server, always, with the minimum order and small-basket fee. The app never computes a total.

"Is stock reserved when I add something?" → No, only at order time. It can run out while you shop.

"What payment methods?" → Apple Pay, and cards with 3-D Secure through our payment provider's SDK. One promo code per order.

"Where is the cart shown?" → A total bar on every catalogue screen, a stepper on every tile, and the cart screen.

"And if the address changes?" → Question 5's delivery area says which hub serves it. A new hub means a different cart.

"Offline?" → Not required. Show the last cart, marked offline.

"Minimum OS?" → iOS 17, SwiftUI, Swift 6.

"What hurts today?" → Steppers that jump back, and double charges after timeouts.

Out of scope, said first: browsing, choosing the address (question 5), order tracking, substitutions, refunds, saved cards.

Required for the prompt

1. Change quantities from any screen, instantly and correctly.
2. Show the server's totals: deposit, delivery fee, minimum order, small-basket fee, promo.
3. Show every stock or price change before the user pays.
4. Place the order exactly once, with Apple Pay or a card with 3-D Secure.

What must feel good: steppers never lag · one cart everywhere · only the server's totals · never charged twice.

Production considerations (say, don't draw): timeouts, safe retries, metrics, payment security (section 12).

Optional follow-ups (add only when asked): offline reading, live stock, stock reservations, more payment methods. The ladder is in section 12.

"The cart lives on the server per hub. Every reply is the whole cart: prices, fees, adjustments, a version. A cart repository calls GET /hubs/{hub}/cart, PUT /hubs/{hub}/cart/items/{sku} and PUT /hubs/{hub}/cart/promo. One shared cart store feeds every screen, and follows question 5's delivery area to a new hub. A quantity use case sends final quantities, one request per product at a time. A place-order use case shows changes first, pays through a payment client, and orders with one key per attempt. An orders repository calls POST /orders, GET /orders/{id} and GET /orders?idempotencyKey=, keeping the key on disk until it knows the outcome."

Nine cards, three chips. Cart isn't a card: the store holds it. The catalogue's tiles read card 5 and call card 3, like card 2.

Not drawn: the shared HTTPClient, and MoneyFormatter, a pure helper. Not on the list yet: the optional follow-ups.

flowchart TB
  subgraph P["PRESENTATION"]
    View["`**1 · Cart screen**
CartView`"] -- "actions → view state" --> VM["`**2 · Cart view model**
CartViewModel`"]
  end
  subgraph D["DOMAIN"]
    Qty["`**3 · Quantity use case**
SerialUpdateQuantityUseCase
app-scoped`"]
    Place["`**4 · Place order use case**
IdempotentPlaceOrderUseCase
app-scoped`"]
    Store["`**5 · Cart store**
CartStore
one cart, every screen`"]
    CartP["`«protocol»
CartRepository`"]
    OrdP["`«protocol»
OrdersRepository`"]
    PayP["`«protocol»
PaymentClient`"]
  end
  Area["`**6 · Delivery area**
reused from Q5`"]
  subgraph DA["DATA"]
    CartImpl["`**7 · Cart repository**
RemoteCartRepository
GET /hubs/{hub}/cart
PUT /hubs/{hub}/cart/items/{sku}
PUT /hubs/{hub}/cart/promo`"]
    OrdImpl["`**8 · Orders repository**
RemoteOrdersRepository
POST /orders
GET /orders/{id}
GET /orders?idempotencyKey=`"]
    Pay["`**9 · Payment client**
PassKitPaymentClient
PassKit + provider SDK`"]
  end
  VM -- "set → outcome" --> Qty
  VM -- "pay → result" --> Place
  VM -- "read → cart" --> Store
  Qty -- "send → cart" --> Store
  Place -- "refresh → cart" --> Store
  Store -- "load → cart" --> CartP
  Place -- "place → status" --> OrdP
  Place -- "pay → token" --> PayP
  Store ~~~ OrdP
  Store ~~~ PayP
  Store -- "follow → hub" --> Area
  CartP ~~~ CartImpl
  CartImpl -. "implements" .-> CartP
  OrdP ~~~ OrdImpl
  OrdImpl -. "implements" .-> OrdP
  PayP ~~~ Pay
  Pay -. "implements" .-> PayP
  class View,VM pres
  class Qty,Place,Store,CartP,OrdP,PayP dom
  class CartImpl,OrdImpl data
  class Pay net
  class Area reuse

How to read it. A solid arrow points from the asker to the answerer: request → reply. Dashed arrows mean implements; the grey card is reused from question 5.

Dependency inversion, in one line. The domain writes the three promises (the chips); cards 7–9 keep them, so the arrows point up and no use case imports PassKit.

The shared store is on this sketch because the prompt puts the cart on several screens.

On Miro: three frames, nine cards, three chips. Point at card 5: "every cart reply lands here, and every screen reads it."

The models everyone shares. Question 5 uses the same Money. The screen never sees a DTO.

struct Money: Hashable, Sendable {
    /// 1,29 € is 129. The server sends minor units.
    let minorUnits: Int
    /// ISO 4217, e.g. "EUR"
    let currency: String
}

struct Cart: Equatable, Sendable {
    let hub: HubID
    /// Bumped by the server on every change
    let version: Int
    let lines: [CartLine]
    /// outOfStock, reduced, priceChanged, promoRemoved
    let adjustments: [Adjustment]
    /// subtotal, deposit, fees, discount, total
    let totals: CartTotals
    /// belowMinimum(missing:), hubClosed, or nil
    let blocker: CheckoutBlocker?
}

1 · Cart screen (CartView)

Job: draws lines, changes, totals and the pay button. It decides nothing.

Interface: reads viewModel.viewState, calls its actions. Choice: a SwiftUI List.

2 · Cart view model (CartViewModel)

Job: turns the shared cart and its checkout phase into one view state.

struct CartViewState: Equatable {
    let lines: [CartLineRow]
    let changes: [ChangeRow]
    /// Formatted, dimmed while a quantity saves
    let totals: TotalsBlock
    /// pay(label), reviewChanges, blocked, updating, placing, checking
    let checkout: CheckoutButton
    let canEdit: Bool
}

@MainActor @Observable
final class CartViewModel {
    init(store: CartStore, updateQuantity: UpdateQuantityUseCase,
         placeOrder: PlaceOrderUseCase, formatter: MoneyFormatter)
    var viewState: CartViewState { get }
    func onAppear() async
    func setQuantity(_ quantity: Int, for sku: SKU) async
    func acknowledgeChanges()
    func applyPromo(_ code: String) async
    func pay(with method: PaymentMethod) async
}

Choice: nothing is computed here. Totals come from the server; MoneyFormatter, a pure helper, divides minor units by the currency's exponent (2 for EUR) and formats with Decimal.FormatStyle.Currency.

3 · Quantity use case (SerialUpdateQuantityUseCase)

Job: sends the latest wanted quantity, one request at a time per product.

/// saved · superseded (a newer tap reports) · locked (an order is placing)
/// · failed(serverQuantity: Int?), nil when no reply said
enum QuantityOutcome: Equatable, Sendable { … }

@MainActor
protocol UpdateQuantityUseCase {
    /// Never throws. Not cancelled by the caller's task:
    /// the write lands, the caller only stops waiting.
    func setQuantity(_ quantity: Int, for sku: SKU) async -> QuantityOutcome
}

@MainActor
final class SerialUpdateQuantityUseCase: UpdateQuantityUseCase {
    init(store: CartStore)
}

Choice: the rule a product manager would state is "the cart ends on my last tap". App-scoped and on the main actor: every tile shares its per-product table, and it writes the main-actor store.

4 · Place order use case (IdempotentPlaceOrderUseCase)

Job: shows changes first, then pays and orders once per attempt.

/// confirmed(OrderID) · reviewChanges · blocked · declined(message:)
/// · checking (no answer yet) · cancelled (sheet closed)
enum CheckoutResult: Equatable, Sendable { … }

@MainActor
protocol PlaceOrderUseCase {
    /// Never throws. Once payment starts, not cancelled by the caller's task.
    func placeOrder(with method: PaymentMethod) async -> CheckoutResult
    /// At launch and on foreground: settles an attempt left from before
    func resumePendingAttempt() async
}

@MainActor
final class IdempotentPlaceOrderUseCase: PlaceOrderUseCase {
    init(store: CartStore, orders: OrdersRepository, payment: PaymentClient)
}

The rule, in steps:

1. Not idle → return. Else set placing before any await; steppers lock everywhere.
2. Refresh. Unseen adjustments → reviewChanges; a blocker → blocked.
3. Make one key for this attempt, pay, and place the order with that key.
4. Confirmed or declined unlocks the cart. No answer sets checking.

Choice: the rule is "never charge twice". Saving the key, retrying and looking it up are delivery, so they live in the orders repository.

5 · Cart store (CartStore)

Job: holds the current hub's cart, wanted quantities and the checkout phase, for every screen.

@MainActor @Observable
final class CartStore {
    init(cart: CartRepository, area: DeliveryAreaRepository)
    /// loading, loaded(Cart), or unavailable(last: Cart?)
    private(set) var server: CartState
    /// Quantities the server hasn't confirmed yet
    private(set) var wanted: [SKU: Int]
    /// idle, placing, or checking
    private(set) var checkout: CheckoutPhase
    /// Wanted, else the server's. nil while unknown.
    func quantity(of sku: SKU) -> Int?
    /// true only when loaded and idle
    var canEdit: Bool { get }
    /// Follows areaChanges() for the app's lifetime
    func start()
    func refresh() async throws -> Cart
    /// Rule-free writes, passed through
    func send(_ quantity: Int, for sku: SKU) async throws -> Cart
    func setPromo(_ code: String?) async throws
    // plus setWanted, setCheckout, markSeen
}

Choices:

• App-scoped, so it owns the hub change: a new hub empties wanted and loads that hub's cart, for every screen at once.
• The stale-result guard is hub plus version. A reply is kept only for the current hub and a newer version.
• No rule, no protocol. Rules live in cards 3 and 4; tests use the real store with a fake repository.

6 · Delivery area (reused from question 5)

Job: says which hub serves the address. Interface: the store uses areaChanges() -> AsyncStream<DeliveryArea> from question 5's DeliveryAreaRepository: it replays the current area, then emits on a hub change. Choice: reused; the cart follows the hub.

7 · Cart repository (RemoteCartRepository)

Job: calls the three cart endpoints and maps CartDTO to Cart.

protocol CartRepository: Sendable {
    /// Changes listed since seenVersion. Throws if unreachable.
    /// Cancelling the caller cancels the read.
    func cart(hub: HubID, seenVersion: Int?) async throws -> Cart
    /// Throws if refused. Run in its own task by the use case.
    func setQuantity(_ quantity: Int, for sku: SKU, hub: HubID) async throws -> Cart
    func setPromo(_ code: String?, hub: HubID) async throws -> Cart
}

Choice: every reply is the whole cart: one shape to map, fresh prices. One caller (the store), one protocol.

8 · Orders repository (RemoteOrdersRepository)

Job: places orders with an Idempotency-Key, looks them up, and keeps the key of an unsettled attempt.

protocol OrdersRepository: Sendable {
    /// Saves the key to disk, then POST /orders. Never throws:
    /// no reply → .unknown, key kept. Not cancelled by the caller.
    func place(_ request: OrderRequest, key: IdempotencyKey) async -> OrderStatus
    /// After 3-D Secure: asks GET /orders/{id} until final, else .unknown
    func finalStatus(of id: OrderID) async -> OrderStatus
    /// nil: nothing pending. Else looks the key up with backoff,
    /// resending with it if the server never got it.
    func resolvePending() async -> OrderStatus?
}

Choices:

• The saved key is bookkeeping about its own requests, so it lives here: a small file, deleted on a definite answer.
• A 409 maps to .cartChanged(Cart), an answer, not an error.

9 · Payment client (PassKitPaymentClient)

Job: shows the Apple Pay sheet or the bank's 3-D Secure check.

@MainActor
protocol PaymentClient {
    /// Shows the sheet. While it waits, calls `charge` with the token
    /// and closes on its answer. nil: the user closed the sheet.
    func payWithApplePay(_ totals: CartTotals,
                         charge: @Sendable (PaymentToken) async -> OrderStatus) async -> OrderStatus?
    /// Returns when the user finishes or leaves: not proof of payment
    func completeBankCheck(_ action: PaymentAction) async
}

Choices:

• PKPaymentAuthorizationController presents without a view, so this lives in data. Its summary items get NSDecimalNumber(mantissa:exponent:isNegative:) from minor units, exponent −2: nothing is rounded.
• A new payment method is a new conformance, not an if.

Why these parts, and no more. Each card changes for one reason:

Each protocol earns a fake. Not added: a composite (nothing combines two sources), a use case for loading or the order lookup, a DI container.

Flow 1 — opening the cart. A new hub does the same, from loading.

sequenceDiagram
  participant V as Cart screen
  participant VM as View model
  participant S as Cart store
  participant R as Cart repo
  V->>VM: onAppear()
  VM->>S: refresh()
  S->>R: cart(hub: h12, seenVersion: 17)
  alt loaded
    R-->>S: h12, version 18, 1 adjustment
    Note over S: current hub and newer, so keep it
    S-->>VM: cart
    VM-->>V: only 2 oat milk, Review changes
  else failed
    R-->>S: error
    Note over S: keep version 17, mark stale
    VM-->>V: stale cart, pay disabled
  end

Flow 2 — three fast taps on "+" (1 → 4).

sequenceDiagram
  participant T as Product tile
  participant U as Quantity use case
  participant S as Cart store
  participant R as Cart repo
  T->>U: setQuantity(2)
  U->>S: wanted 2, send(2)
  S->>R: PUT quantity 2
  T->>U: setQuantity(3), then 4
  U->>S: wanted 4
  Note over U: one in flight, remember 4
  R-->>S: cart, quantity 2
  Note over U: wants 4, server has 2
  U->>S: send(4)
  S->>R: PUT quantity 4
  alt accepted
    R-->>S: cart, quantity 4
    U->>S: clear wanted
  else only 3 in stock
    R-->>S: cart, quantity 3, reduced
    U->>S: clear wanted
    S-->>T: 3, only 3 left
  end

The earlier calls return superseded.

Flow 3 — paying with Apple Pay, and the reply never arrives.

sequenceDiagram
  participant U as Place order
  participant P as Payment client
  participant O as Orders repo
  participant S as Cart store
  U->>S: checkout placing
  U->>P: payWithApplePay(totals)
  P-->>U: token, sheet waiting
  U->>O: place(order, key K)
  Note over O: K saved, then POST
  alt confirmed
    O-->>U: confirmed
    U->>S: checkout idle, refresh
  else timeout
    O-->>U: unknown
    Note over P: sheet closes
    U->>S: checkout checking
    U->>O: resolvePending()
    Note over O: GET /orders?idempotencyKey=K
    O-->>U: confirmed
    U->>S: checkout idle, refresh
  end

GET  /v1/hubs/{hub}/cart?seenVersion=17
     → { "hub": "h12", "version": 18,
         "lines": [ { "sku", "name", "quantity",
                      "unitPrice": { "minorUnits": 129, "currency": "EUR" },
                      "deposit":   { "minorUnits": 25,  "currency": "EUR" } } ],
         "adjustments": [ { "sku", "kind": "reduced", "to": 2 } ],
         "totals": { "subtotal", "deposit", "fees", "total" },
         "blocker": null }

PUT  /v1/hubs/{hub}/cart/items/{sku}   { "quantity": 3 }     → the whole cart
PUT  /v1/hubs/{hub}/cart/promo         { "code": "SPRING" }  → the whole cart

POST /v1/orders   Idempotency-Key: 7f3c…
     { "hub": "h12", "cartVersion": 18,
       "payment": { "method": "applePay", "token": "…" } }
     → 201 confirmed · 202 needsAction (3-D Secure) · 402 declined
     → 409 cartChanged, with the new cart

GET  /v1/orders/{id}                 → { "orderId", "status" }
GET  /v1/orders?idempotencyKey=7f3c… → { "orderId", "status" }  or 404

• Every cart reply is the whole cart, priced by the server, tagged with hub and version.
• A quantity PUT is safe to repeat by nature; an order POST only because of the key. A repeat gets the first result.
• The order names the cart version the user saw, so a changed cart gets 409, not a different charge. The cart is personal, never on a shared CDN.

The decision: the store shows the wanted quantity at once, and the use case keeps one request per product in flight, always the latest.

1. Each tap sets wanted[sku] before any await. Tile, badge and cart all show it.
2. If a request for this product is in flight, stop. The earlier call becomes superseded.
3. Otherwise send the wanted value through the store.
4. When the reply lands, the store applies it. If wanted still differs, send again. If not, clear wanted and report saved.

Five fast taps usually make two requests.

Rollback, only for the latest, to the server's number: the tile shows it with "Couldn't update". A clamp ("only 3 left") isn't a failure, just a reply of 3.

Taps during checkout. Pay sets placing first: steppers disable, and a tap already on its way returns locked. A quantity still saving shows "Updating…" and Pay waits. Otherwise the PUT would bump the version and fail the order with a 409.

Unknown is not zero. Steppers wait for the cart, so a guessed 0 never overwrites the iPad's 2.

Rejected: debounce alone. Two sends can still overlap and land out of order.

The decision: the server reports every change it made on its own as a line adjustment, and the user sees it before paying.

1. Any cart reply can carry adjustments.
2. At checkout the use case refreshes first. Any adjustment returns reviewChanges before the sheet opens.
3. As the last guard, POST /orders carries cartVersion. A change in the last seconds gets 409, and no charge.

The screen shows a row per affected line ("Bananas: now 1,49 €, was 1,29 €"), the new total, and "Review changes" until the user taps OK. Then "Pay 23,40 €". A belowMinimum blocker shows "Add 3,10 € more"; the phone never knows thresholds.

A new hub. The store follows areaChanges(): it empties wanted, shows loading and loads the new hub's cart. An old-hub reply fails the hub check. Carrying items over is the server's call; moved items arrive as adjustments.

Rejected: update the total silently. Simpler, but the user agrees to a price they never saw.

The decision: one idempotency key per checkout attempt, saved before the request leaves. An unknown outcome is answered by asking about that key: never a new order, never "failed".

1. On Pay, the use case makes key K. The orders repository saves it, then sends POST /orders with K.
2. No reply: place returns unknown, the phase becomes checking, and resolvePending() asks GET /orders?idempotencyKey=K with backoff.
3. Found: show its status. Not found: the server never got it, so resend with the same K.
4. A definite answer deletes the saved key. Only a new attempt gets a new one.

After a relaunch, resumePendingAttempt() runs first and the store starts in checking.

Apple Pay. The order is placed inside paymentAuthorizationController(_:didAuthorizePayment:handler:) while the sheet waits. Its PKPaymentAuthorizationResult has no "unknown", so place makes one bounded request; on a timeout the sheet closes and the cart says "Checking your order…".

Card with 3-D Secure. POST /orders answers needsAction and the payment client shows the bank's check. Its "done" isn't proof: finalStatus(of:) asks the server.

Rejected: just disable the button. It stops double taps, not retries or relaunches.

Failures

Production notes (short, not on the board)

• Networking: a timeout per request; retry PUTs freely, POST /orders only with its key; honour Retry-After on 429. Cancel reads, never writes.
• Caching: the cart is personal, never HTTP-cached.
• Metrics: tap-to-confirmed time, rollbacks, adjustments per checkout, unknown outcomes. Security: card details go only to the provider SDK.

Scale, back of the envelope: orders a day × taps per order, fewer after serializing. 200,000 × 30 is 6 million taps a day; small cart replies matter more than the client architecture.

Grow only when asked

Cart on every screen       → one shared store (here already: the prompt asks)
Read the cart offline      → persist the last cart, read-only
Live stock while browsing  → push or a socket per hub
Hold stock while paying    → a server reservation with a countdown
More payment methods       → one more payment client conformance

Answer out loud first, then open.

Scope and architecture

Quantities

Money and changes

Placing the order

Production and change

14+ is a pass.A zero names the thing to read about next.:::