05 · A grocery catalogue that depends on the address

• 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.
• Store — in-memory state that several screens show at once. Here: question 6's 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 (dark store) — a small warehouse that only serves deliveries. Each address has one.
• Stock — how many of a product the hub has right now.
• Server-driven section — a block of the home the server chooses and orders.
• Cache key — the label a saved response is filed under. A new key means a new copy.
• Deposit (Pfand) — a refundable charge on bottles and cans, shown beside the price.
• Minor units — money as a whole number of cents: 1,99 € is 199.

"How does an address become a hub?" → The server decides. Send a location; it answers with a hub or "we don't deliver there".

"No address yet?" → Let them look around a default hub. Ordering needs an address.

"How many products per hub?" → About 3,000. Similar across hubs, not the same.

"Same price everywhere?" → Per hub, yes; never per user. Discounts come from the server.

"Who decides the home screen?" → The server: banners, categories, "buy again", product rows. Marketing adds new kinds of blocks.

"How fast does stock change?" → Popular items sell out in minutes. Checkout always re-checks. Hubs close at night.

"Offline?" → Show what you have. Nobody orders offline.

"Cart?" → Question 6. Tiles have its stepper.

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

Out of scope, said first: search, the cart and checkout (question 6), the address picker, the courier map, recommendations. Photos come from question 1's image loader.

Required for the prompt

1. Resolve the address to a hub; handle no address, out of area and closed.
2. Show the home the server arranges, skipping block types the app doesn't know.
3. Open a category and scroll its products.
4. Tiles with price, discount, deposit and stock, fresh enough to trust while browsing.

What must feel good: a fast home from cache · stock never shown as known when it isn't · two hubs never mixed · exact prices.

Production considerations (say, don't draw): HTTP caching, retries, timeouts, metrics per hub (section 12).

Optional follow-ups (add only when asked): search, live stock, the whole catalogue offline, a product detail screen. The ladder is in section 12.

"A delivery-area repository is the one owner of the hub: it calls GET /delivery-area and streams area changes to whoever follows them. Every catalogue request carries the hub in its path: GET /hubs/{hub}/home for the server's sections, GET /hubs/{hub}/categories/{id}/products for a category, and GET /hubs/{hub}/stock on its own, because stock goes stale in seconds. A products repository maps the first two; a stock repository caches counts for 30 seconds. A read-only composite fills in stock for the first screenful. The view model follows the hub, asks for stock as sections appear, and drops any reply for an old hub. Steppers are question 6's cart."

Eight cards, three chips. Storefront and Product aren't cards: the composite returns them. The category screen has the same shape, so it isn't drawn twice.

Not drawn: NavigationStore, the app's path holder, which follows areaChanges() and pops to the root on a new hub; MoneyFormatter, a pure helper; the shared HTTPClient. Not on the list yet: a use case. Loading has no product rule, and the one write with a rule, the quantity, is question 6's.

---
config:
  layout: elk
---
flowchart TB
  subgraph P["PRESENTATION"]
    View["`**1 · Home screen**
HomeView`"] -- "actions → view state" --> VM["`**2 · Home view model**
HomeViewModel`"]
  end
  Img["`**3 · Image loader**
reused from Q1`"]
  Cart["`**4 · Cart**
reused from Q6`"]
  subgraph D["DOMAIN"]
    AreaP["`«protocol»
DeliveryAreaRepository`"]
    CatP["`«protocol»
CatalogueRepository`"]
    StockP["`«protocol»
StockRepository`"]
  end
  subgraph DA["DATA"]
    AreaImpl["`**6 · Delivery area repository**
RemoteDeliveryAreaRepository
GET /delivery-area`"]
    Comp["`**5 · Composite catalogue repository**
CompositeCatalogueRepository
products + stock → Storefront`"]
    Prod["`**7 · Products repository**
RemoteProductsRepository
GET /hubs/{hub}/home
GET /hubs/{hub}/categories/{id}/products`"]
    StockImpl["`**8 · Stock repository**
RemoteStockRepository
GET /hubs/{hub}/stock`"]
  end
  View -- "URL → photo" --> Img
  VM -- "follow → hub" --> AreaP
  VM -- "hub → storefront" --> CatP
  VM -- "IDs → stock" --> StockP
  VM -- "set → outcome" --> Cart
  AreaP ~~~ AreaImpl
  AreaImpl -. "implements" .-> AreaP
  CatP ~~~ Comp
  Comp -. "implements" .-> CatP
  StockP ~~~ StockImpl
  StockImpl -. "implements" .-> StockP
  Comp -- "hub → sections" --> Prod
  Comp -- "IDs → stock" --> StockImpl
  class View,VM pres
  class AreaP,CatP,StockP dom
  class AreaImpl,Comp,Prod,StockImpl data
  class Img,Cart reuse

How to read it. A solid arrow points from the asker to the answerer: request → reply. Dashed arrows mean implements; the grey cards are reused from questions 1 and 6.

Dependency inversion, in one line. The domain writes the three promises (the chips); cards 5, 6 and 8 keep them, so the arrows point up and the view model never sees an endpoint.

Shared state on this sketch: the hub is on every screen, so its one owner, card 6, is drawn. The cart store is shared too, and it's question 6's.

On Miro: three frames, eight cards, three chips. Point at card 6: "one owner of the hub; everything that depends on it follows its stream."

The models everyone shares. Money is question 6's, unchanged. 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
}

/// served(HubID), outOfArea, or browsing(defaultHub: HubID)
enum DeliveryArea: Equatable, Sendable { … }

struct Storefront: Equatable, Sendable {
    /// The hub it was built for: the stale-result guard checks it
    let hub: HubID
    /// open, or closed(opensAt:)
    let hours: HubHours
    /// The server's order, unknown types already removed
    let sections: [HomeSection]
}

/// banners · categories · products(title:) · buyAgain, each with an id
enum HomeSection: Equatable, Sendable, Identifiable { … }

struct Product: Equatable, Sendable, Identifiable {
    /// The same SKU question 6's cart uses
    let id: SKU
    let name: String
    /// URL, width, height
    let image: ImageRef
    let price: Money
    let originalPrice: Money?
    /// Shown beside the price, never added in
    let deposit: Money?
    /// Required by German price rules: per kg or litre
    let unitPrice: UnitPrice?
    /// inStock(count), outOfStock, or unknown (not asked yet, or failed)
    var availability: Availability
}

1 · Home screen (HomeView)

Job: draws the address header, a closed or offline notice, and the sections. It decides nothing.

Interface: reads viewModel.viewState; reports appear, foreground, pull to refresh, a section appearing, and stepper taps. Category taps are NavigationLink(value:), handled by navigationDestination(for:destination:).

Choices:

• A LazyVStack of sections, product rows as horizontal lazy stacks, tiles sized before photos arrive.
• .refreshable for pull to refresh; scenePhase tells the view model the app came back.
• The NavigationStack path lives in NavigationStore, not here and not in the view model, because the category screen needs the same reset.

2 · Home view model (HomeViewModel)

Job: follows the hub, loads its storefront, asks for stock as sections appear, and builds one view state.

struct HomeViewState: Equatable {
    /// "Torstraße 1" or "Add your address"
    let addressTitle: String
    /// closed "Opens at 07:00", offline "May be out of date", or nil
    let notice: Notice?
    /// loading, sections([SectionRow]), outOfArea(message), failed(message)
    let content: ContentState
    /// false when closed, offline, browsing or out of area
    let canOrder: Bool
}

struct ProductTile: Equatable, Identifiable {
    let id: SKU
    let name: String
    let imageURL: URL
    /// All formatted: "2,49 €", struck "2,99 €", "+ 0,25 € Pfand", "9,96 €/kg"
    let price: String
    let originalPrice: String?
    let deposit: String?
    let unitPrice: String?
    /// none, low("Only 2 left"), or out
    let stockBadge: StockBadge
    /// From the cart store. nil while the cart loads.
    let quantity: Int?
    let canAdd: Bool
}

@MainActor @Observable
final class HomeViewModel {
    init(area: DeliveryAreaRepository, catalogue: CatalogueRepository,
         stock: StockRepository, cart: CartStore,
         updateQuantity: UpdateQuantityUseCase, formatter: MoneyFormatter)
    var viewState: HomeViewState { get }
    func onAppear() async
    func refresh() async
    func onForeground() async
    func sectionAppeared(_ id: SectionID) async
    func setQuantity(_ quantity: Int, for sku: SKU) async
}

Choices:

• The stale-result guard is the hub. Every request names it, every reply carries it, and a reply whose hub isn't the current one is dropped. Cancelling the old load only saves bandwidth.
• It doesn't decide when stock is stale. It reports moments (a section appearing, foreground); the stock repository's 30-second cache decides whether to call.
• Small separate states, not one enum. A closed or offline hub still has sections.

3 · Image loader (reused from question 1)

Job: gives each tile its photo at the tile's size. Interface: URL plus display size, cancelled when the tile goes. Choice: photo URLs carry no hub, so they stay cached across a hub switch.

4 · Cart (reused from question 6)

Job: the stepper's quantity and its write.

Interface: the tile reads CartStore.quantity(of:) and canEdit, and calls UpdateQuantityUseCase.setQuantity(_:for:), both keyed by the same SKU. That's all this chapter needs.

Choice: reused. Question 6's store also follows areaChanges(), so the badge and tiles switch hub together.

5 · Composite catalogue repository (CompositeCatalogueRepository)

Job: combines a hub's products with their stock for the first screenful. It owns no source and never writes.

protocol CatalogueRepository: Sendable {
    /// Sections for this hub, with stock for the first two sections.
    /// Other products stay .unknown. Throws only if sections failed.
    /// Cancelling the caller cancels both requests.
    func storefront(hub: HubID) async throws -> Storefront
    /// One page of 20, with its stock. Same failure rules.
    func products(hub: HubID, category: CategoryID,
                  after cursor: Cursor?) async throws -> ProductPage
}

final class CompositeCatalogueRepository: CatalogueRepository {
    init(products: ProductsRepository, stock: StockRepository)
}

How it combines:

1. Ask the products repository for the hub's sections: Products with stock unknown.
2. Ask the stock repository for the products in the first two sections (a screenful).
3. Set those products' availability; if step 2 failed, leave them unknown.

Choices:

• Stock failing never hides the catalogue, and it only combines app models.
• The trade-off, said out loud: two requests add latency. They're separate because they go stale at different speeds. If the first load is too slow, I'd ask the server for a stock snapshot inside the home reply.

6 · Delivery area repository (RemoteDeliveryAreaRepository)

Job: the one owner of the hub. It resolves an address with GET /delivery-area and tells every follower when the hub changes.

protocol DeliveryAreaRepository: Sendable {
    /// Throws if unreachable.
    func area() async throws -> DeliveryArea
    /// Replays the current area, then emits only when the hub changes.
    /// One stream per caller. Finishes when the caller's task is cancelled.
    func areaChanges() -> AsyncStream<DeliveryArea>
    /// Called by the address picker. Throws if unreachable: the old area stays.
    func setAddress(_ address: Address) async throws -> DeliveryArea
}

Choices:

• An actor, app-scoped. The home, the category screen, NavigationStore and question 6's cart store all follow the same stream.
• A new address in the same hub emits nothing, so no cache or cart is touched. It keeps the last address and area in a small file, so launch starts from the last hub.

7 · Products repository (RemoteProductsRepository)

Job: fetches GET /hubs/{hub}/home and GET /hubs/{hub}/categories/{id}/products, and maps them.

/// Data-internal: the composite's promise
protocol ProductsRepository: Sendable {
    /// Unknown section types dropped and counted. Throws on failure.
    func sections(hub: HubID) async throws -> [HomeSection]
    func page(hub: HubID, category: CategoryID, after cursor: Cursor?) async throws -> ProductPage
}

Choices:

• The hub is in the URL path, so it's in every cache key for free: URLCache, the CDN, memory. A header would hide it from the key.
• Offline, it asks with .returnCacheDataDontLoad and marks the result stale.

8 · Stock repository (RemoteStockRepository)

Job: fetches counts from GET /hubs/{hub}/stock?ids= and keeps them for 30 seconds.

protocol StockRepository: Sendable {
    /// Cached counts younger than 30 s, the rest fetched in one request.
    /// Never throws: a failed fetch returns .unknown, never .outOfStock.
    func availability(of skus: [SKU], at hub: HubID) async -> [SKU: Availability]
}

Choice: a memory cache keyed by hub and SKU, an actor. Never on disk: old stock is worse than none.

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

Each protocol earns a fake. Not added: a use case for loading (no rule), a catalogue database, a product store, a DI container. Constructor injection is enough.

Flow 1 — opening the home screen. A category page is the same, with a cursor.

sequenceDiagram
  participant VM as View model
  participant A as Area repo
  participant C as Composite
  participant P as Products repo
  participant S as Stock repo
  VM->>A: areaChanges()
  A-->>VM: served, h12
  VM->>C: storefront(hub: h12)
  C->>P: sections(hub: h12)
  P-->>C: 8 sections, stock unknown
  C->>S: availability(first 2 sections)
  alt stock loaded
    S-->>C: counts
  else stock failed
    S-->>C: all unknown
  end
  C-->>VM: Storefront, hub h12
  Note over VM: later sections ask on appear

Flow 2 — the user changes address while a load is still running.

sequenceDiagram
  participant AP as Address picker
  participant A as Area repo
  participant N as Navigation store
  participant VM as View model
  participant C as Composite
  AP->>A: setAddress(work)
  Note over A: GET /delivery-area
  alt same hub
    A-->>AP: served, h12
  else new hub
    A-->>AP: served, h07
    A-->>N: area h07
    Note over N: pop to root
    A-->>VM: area h07
    VM->>C: storefront(hub: h07)
    Note over VM: late h12 reply is dropped
    C-->>VM: Storefront, hub h07
  end

Question 6's cart store follows the same stream and loads the h07 cart.

GET  /v1/delivery-area?lat=52.529&lng=13.401
     → { "status": "served", "hub": "h12" }   or { "status": "outOfArea" }

GET  /v1/hubs/{hub}/home?sections=banners,categories,products,buyAgain
     → { "hours": { "isOpen": true, "opensAt": null },
         "sections": [ { "id": "s1", "type": "products", "title": "Fresh fruit",
           "items": [ { "sku": "p1", "name": "Bananas", "image": { … },
             "price": { "minorUnits": 199, "currency": "EUR" },
             "originalPrice": null, "deposit": null,
             "unitPrice": { "minorUnits": 199, "per": "kg" } } ] } ] }

GET  /v1/hubs/{hub}/categories/{id}/products?cursor={opaque}&limit=20
     → { "items": [ product ], "nextCursor": "…" }   // null at the end

GET  /v1/hubs/{hub}/stock?ids=p1,p2,…
     → { "asOf": "2026-10-20T10:42:05Z", "stock": { "p1": 12, "p2": 0 } }

The cart's endpoints are question 6's.

• The hub is in the path, so it's in every cache key. Category pages are the same for everyone at a hub, so a CDN can keep them for minutes. The home is personal ("buy again"), never shared.
• Money is minor units plus a currency, as in question 6. The client never does arithmetic on prices.
• The client says which section types it can draw. The server leaves out the rest; the client still skips anything unknown.

Decision: the server arranges the home from a fixed set of typed sections. The app draws each type it knows and skips the rest.

1. Decode by type. Each section has a type and an id; the mapper decodes the known ones into HomeSection cases.
2. Unknown types are skipped, not fatal, and counted, so a mistake shows on a dashboard.
3. The client declares what it can draw (?sections=…). The server leaves out the rest, or sends an older equivalent.
4. A new type is additive: one decode case and one view case, both checked by the compiler.

Say it honestly: new content and order need no release. New layouts do, unless built from existing types. A registry (type → decoder and view) is the next step only if blocks ship weekly.

Rejected: a generic layout language. It's a second UI framework to maintain and keep accessible.

Decision: one owner of the hub, and the hub in every request. A new hub just asks for different keys; nothing must be cleared to be correct.

1. The delivery area repository resolves the new address. Same hub: nothing emits. New hub: areaChanges() emits.
2. Every follower reacts on its own: NavigationStore pops to the root, the view model shows "loading" and asks for storefront(hub: h07), the cart store loads the h07 cart.
3. A late h12 reply is dropped by the stale-result guard: its hub isn't the current one. Cancelling is cooperative, so a reply can still land.
4. Stock is keyed by hub too, so h12 counts are never shown at h07.

Clearing memory only saves space. The disk cache keeps the old hub for a fast switch back.

No address: browse the default hub, prices shown, stock hidden, the stepper asks for an address. Out of area: a message and "Change address", no catalogue.

Rejected: the hub in a header the API client adds. Two hubs then share one URL, and a cache can serve one hub's stock to another.

Decision: stock is a hint for browsing, never a promise. Asked for only what's on screen, kept 30 seconds, and checkout has the final word.

1. Only what's on screen. The composite fills the first two sections. Each later section asks when it appears, about 10 SKUs.
2. Natural moments, not a timer: appear, foreground (scenePhase becomes active), pull to refresh. The repository answers from cache if it's younger than 30 seconds.
3. Three tile states: in stock ("Only 2 left" when low), "Out of stock" with the stepper hidden, or no badge when unknown. Unknown is never drawn as out.
4. Checkout validates. The server checks real stock, and question 6 shows what changed.

Offline: the last catalogue, "May be out of date", no stock badges, canOrder false.

Rejected: polling every few seconds, or a socket per user. Battery and server load for browsing that only needs to be roughly right. Switch if the product shows live counts on purpose.

Failures

Production notes (short, not on the board)

• Networking: a timeout per request; retry reads with backoff; honour Retry-After on 429; cancel loads for screens that are gone.
• Caching: the server's Cache-Control decides: minutes for categories, seconds for stock. A larger URLCache disk keeps the last home per hub.
• Metrics: time to first home, cache hits, skipped sections by type, stock failures, and "out of stock at checkout" per hub, which says whether 30 seconds is fresh enough.
• Privacy: the location goes only to /delivery-area; after that the hub ID is enough.

Scale, back of the envelope: 3,000 products × about 500 bytes is 1.5 MB a hub, so a daily full download is a real option later. Stock costs more: 100,000 users × 5 foregrounds × 20 SKUs is 10 million lookups a day, which is why only what's on screen is asked.

Grow only when asked

Search                      → a search endpoint per hub
Product detail screen       → reads the same catalogue and cart
Whole catalogue offline     → a daily download per hub, in a database
Live stock                  → shorter cache, then push, only if needed
Stock shown on two screens  → a shared stock store

Answer out loud first, then open.

Scope and architecture

Address and hub

Server-driven home

Stock and money

Production and change

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