15 · Prices that move several times a second

• 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. Not needed here yet.
• 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.
• WebSocket — one connection that stays open, so the server can push messages.
• Snapshot, update — a snapshot is the full current price; an update says only what changed.
• Sequence number — a counter on every update, so a missing one is noticed.
• Coalescing — keeping only the newest price per instrument between redraws.
• Tick — the fixed moment, four times a second, when the screen redraws.
• Stale — a price that may be out of date, shown with its time.
• Backoff with jitter — waiting longer after each failed reconnect, with a random spread.

"What instruments, and what precision?" → Stocks and ETFs, quoted in euros or dollars to the cent. FX and crypto later.

"How fast do prices move?" → A busy stock updates up to ten times a second. Fifty instruments, so a few hundred messages a second at peak.

"What does a row show?" → Name, last price, change since yesterday's close, and a short flash when the price moves.

"Is there a socket already?" → Yes, a WebSocket that pushes prices. Tell me what you need from it.

"Other screens with live prices?" → An instrument detail screen later. Just the watchlist now.

"Editing the watchlist? Trading?" → Both out of scope.

"What if prices can't be live?" → Regulators care that we never show an old price as current.

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

"What hurts today?" → The app gets hot, the list stutters, and after a tunnel the prices sometimes freeze without saying so.

Out of scope, said first: trading, editing the watchlist, charts, alerts, order books, the detail screen.

Required for the prompt

1. Show the watchlist with live prices and change since close.
2. A brief flash when a price moves, up or down.
3. Mark any price that may be out of date, with its time, and recover by itself.

What must feel good: smooth while prices stream · never a wrong or old price shown as live · cool phone, modest data · calm for VoiceOver.

Production considerations (say, don't draw): auth on the socket, server-side conflation, metrics. See section 12.

Optional follow-ups (add only when asked):

An instrument detail screen  → the same use case, a second caller
A portfolio total in the tab → a shared quote store
Charts per instrument        → history endpoint, a frame-rate tick
FX and crypto                → a price scale per instrument

"I'll add each of these when the requirement appears."

"A watchlist repository calls GET /watchlist for the instruments in order. One socket connection holds WSS /quotes while the app is in the foreground. A quotes repository subscribes only to the rows on screen, takes a snapshot then numbered updates, and resyncs any instrument whose numbers jump. A watch use case keeps the newest price per instrument and hands the view model one batch per tick, four times a second, with any price we can't vouch for marked stale. The view model turns batches into rows, and each row redraws only when its own values change."

Seven cards, two chips. Quote isn't a card; it's written on card 6.

No use case for loading the list: it's one call with no rule. Watching prices has one a product manager would say: "at most four refreshes a second, always the newest, and never an old price shown as live".

Not drawn: the HTTPClient card 5 uses, and a NetworkMonitor (protocol NetworkStatus) over NWPathMonitor that tells card 7 to retry at once when the network comes back. Not on the list yet: everything under "optional follow-ups".

flowchart TB
  subgraph P["PRESENTATION"]
    View["`**1 · Watchlist screen**
WatchlistView`"] -- "actions → view state" --> VM["`**3 · Watchlist view model**
WatchlistViewModel`"]
    View -- "row state → row" --> Row["`**2 · Price row**
PriceRowView
flash, fixed width`"]
  end
  subgraph D["DOMAIN"]
    Watch["`**4 · Watch use case**
ThrottledWatchQuotesUseCase
one batch per tick`"]
    WL["`«protocol»
WatchlistRepository`"]
    QP["`«protocol»
QuotesRepository`"]
  end
  subgraph DA["DATA"]
    WLImpl["`**5 · Watchlist repository**
RemoteWatchlistRepository
GET /watchlist`"]
    Quotes["`**6 · Quotes repository**
LiveQuotesRepository
DTO → Quote, gap → resync`"]
    Sock["`**7 · Socket connection**
QuoteSocketConnection
WSS /quotes`"]
  end
  VM -- "watch → batches" --> Watch
  Watch -- "events → quotes" --> QP
  VM -- "load → instruments" --> WL
  Watch ~~~ WL
  QP ~~~ Quotes
  Quotes -. "implements" .-> QP
  WL ~~~ WLImpl
  WLImpl -. "implements" .-> WL
  Quotes -- "subscribe → frames" --> Sock
  class View,VM,Row pres
  class Watch,WL,QP dom
  class WLImpl,Quotes data
  class Sock net

How to read it. A solid arrow points from the asker to the answerer: request → reply. Dashed arrows mean implements; orange is the one network connection.

Dependency inversion, in one line. The domain writes the two promises (the chips); cards 5 and 6 keep them, so both dashed arrows point up and the view model and use case never see a socket.

Where the rates change. Cards 7, 6 and 4 run off the main actor at the network's rate; only card 4's tick reaches card 3.

No shared store on this sketch: one screen shows the prices. A portfolio total in the tab bar would add one.

On Miro: three frames (blue, purple, green), seven cards, two chips, six solid arrows. Point at card 4: "hundreds of messages in, four batches a second out."

The models everyone shares. The screen never sees a DTO.

struct Money: Equatable, Sendable {
    /// Cents for EUR and USD
    let minorUnits: Int
    /// ISO code, which gives the exponent
    let currency: String
}

struct Quote: Equatable, Sendable {
    let symbol: Symbol
    let last: Money
    let previousClose: Money
    /// Server time of this price
    let time: Date
}

struct Instrument: Identifiable, Hashable, Sendable {
    let id: Symbol
    let name: String
}

Never Double: 0.1 + 0.2 isn't 0.3 in binary, and a price must add up to the cent. The view model formats Decimal(minorUnits) scaled by the currency's exponent with Decimal.FormatStyle.Currency.

1 · Watchlist screen (WatchlistView)

Job: draws the list and the banner, and reports which rows are on screen. It decides nothing.

Interface: reads viewModel.viewState; calls onAppear(), visibleRowsChanged(_:), retry().

Choice: a SwiftUI List with one PriceRowView per row, identified by symbol. On iOS 17 rows report visibility from .onAppear and .onDisappear; on iOS 18 onScrollTargetVisibilityChange reports the visible set directly.

2 · Price row (PriceRowView)

Job: draws one row from its row state: name, price, change, the flash and the stale time.

Interface: PriceRowView(state: PriceRowState), an Equatable view (or wrapped in .equatable()), so SwiftUI skips it when its state hasn't changed.

Choices:

• No layout change on a tick. Digits use monospacedDigit() and the price column has a fixed width, so a new price never moves its neighbours.
• The flash is a background tint that fades, drawn behind the text, never a size change. With Reduce Motion on (accessibilityReduceMotion), only the arrow and colour change.
• Stale time with Text(date, style: .relative). The system updates "12 sec ago" itself, so the age costs the view model nothing.

3 · Watchlist view model (WatchlistViewModel)

Job: loads the instruments, watches the visible ones, and turns each batch into rows.

struct WatchlistViewState: Equatable {
    let rows: [PriceRowState]
    /// loading, loaded, failed(message): the instrument list
    let list: LoadState
    /// nil, or "Reconnecting. Prices may be out of date."
    let banner: String?
}

struct PriceRowState: Equatable, Identifiable {
    let id: Symbol
    let name: String
    /// "€182.40", nil until the first quote
    let price: String?
    /// "+1.24 %"
    let change: String?
    /// up or down, plus a counter so the same direction flashes again
    let flash: Flash?
    /// nil while live, else the time of the last price
    let staleSince: Date?
    /// "Acme, 182 euros 40, up 1.2 percent"
    let accessibilityLabel: String
}

@MainActor @Observable
final class WatchlistViewModel {
    init(watchlist: WatchlistRepository, quotes: WatchQuotesUseCase)

    var viewState: WatchlistViewState { get }

    func onAppear() async
    /// The rows on screen, once scrolling settles
    func visibleRowsChanged(_ ids: Set<Symbol>)
    func retry() async
}

Choices:

• One watch at a time. A new visible set starts a new watch and cancels the old task; the repository keeps overlapping subscriptions open (section 11).
• The stale-result guard is a watch generation. A batch from a cancelled watch carries the old generation and is dropped.
• Formatting happens here, once per changed row per tick.
• It joins two sources by symbol, not a composite: the list loads once and the prices tick, so a composite would only turn a list into a stream.

4 · Watch use case (ThrottledWatchQuotesUseCase)

Job: keeps the newest quote per symbol and emits at most one batch per tick, with untrusted prices marked stale.

enum Freshness: Equatable, Sendable {
    case live
    case stale(since: Date)
}

struct LiveQuote: Equatable, Sendable {
    /// nil until the first snapshot
    let quote: Quote?
    let freshness: Freshness
}

struct QuoteBatch: Equatable, Sendable {
    /// Only the symbols whose quote or freshness changed
    let changes: [Symbol: LiveQuote]
}

protocol WatchQuotesUseCase: Sendable {
    /// Replays the latest known quotes first, then one batch per tick.
    /// Never throws: a dead feed shows as stale, not as an error.
    /// One stream per caller, off the main actor. Finishes when the
    /// caller's task is cancelled, which releases the symbols.
    func watch(_ symbols: Set<Symbol>) -> AsyncStream<QuoteBatch>
}

struct ThrottledWatchQuotesUseCase: WatchQuotesUseCase {
    init(quotes: QuotesRepository, clock: any Clock<Duration>, tick: Duration)
}

Choices:

• The rule a product manager would state: at most four refreshes a second, always the newest, and never an old price shown as live. That's why it's a use case.
• No per-item state of its own. Each watch call gets its own buffer inside its stream, so the type is a plain struct and needs no app-wide instance.
• The tick is injected with the clock: 250 ms, or 1 s in Low Power Mode (isLowPowerModeEnabled). Tests drive a fake clock.

5 · Watchlist repository (RemoteWatchlistRepository)

Job: fetches GET /watchlist and maps each DTO to an Instrument.

protocol WatchlistRepository: Sendable {
    /// In display order. Throws on failure.
    /// Cancelling the caller cancels the request.
    func instruments() async throws -> [Instrument]
}

Choice: a thin adapter; the server owns the order.

6 · Quotes repository (LiveQuotesRepository)

Job: owns live quotes: which symbols are subscribed, the last sequence number of each, and the latest quote. It maps frames to Quotes and resyncs any symbol with a gap.

enum QuoteEvent: Sendable {
    case quote(Quote)
    /// May be out of date (gap or disconnect) until the next snapshot
    case interrupted(Set<Symbol>)
}

protocol QuotesRepository: Sendable {
    /// Replays the cached quote of each symbol, then events in order.
    /// Never throws. One stream per caller. Cancelling releases the
    /// symbols, unsubscribed after a short grace if nobody else wants them.
    func events(for symbols: Set<Symbol>) -> AsyncStream<QuoteEvent>
}

actor LiveQuotesRepository: QuotesRepository {
    init(socket: QuoteSocket)
}

Choices:

• A count per symbol, a diff on the wire. Two callers watching the same symbol mean one subscription, and only additions and removals are sent.
• Sequence numbers per symbol (section 10). The check is a pure helper inside this card, because it changes with the payload.
• The snapshot comes over the same socket, so it's ordered with the updates. An HTTP snapshot would race the stream.

7 · Socket connection (QuoteSocketConnection)

Job: holds one WebSocket while the app is in the foreground, reconnects when it drops, and hands frames to card 6.

/// Data-internal: what card 6 needs
protocol QuoteSocket: Sendable {
    /// Frames as DTOs, plus .connected after every (re)connect.
    /// One subscriber, the quotes repository.
    func frames() -> AsyncStream<SocketEvent>
    /// Throws if not connected; card 6 resends after .connected
    func send(_ command: QuoteCommandDTO) async throws
}

actor QuoteSocketConnection: QuoteSocket {
    init(session: URLSession, url: URL, tokens: TokenProvider)
    /// Driven by scenePhase: active → start, background → stop
    func start()
    func stop()
}

Choices:

• URLSessionWebSocketTask, read with receive() in a loop. No third-party library.
• A quiet socket can look open. The server sends a heartbeat every second; three seconds of silence, or a missed sendPing reply, means dead: close and reconnect.
• Backoff with jitter: 0.5 s, 1, 2, 4, capped at 30 s, each with a random spread so a crowd doesn't reconnect at once. A network-back signal retries at once.

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

Each protocol earns a fake. Not added: a composite, a store, a use case for loading, a protocol for the view model.

Flow 1 — opening the watchlist.

sequenceDiagram
  participant VM as View model
  participant W as Watchlist repo
  participant U as Watch use case
  participant Q as Quotes repo
  participant S as Socket
  VM->>W: instruments()
  W-->>VM: 50 instruments
  VM->>U: watch(12 visible)
  U->>Q: events(for: 12)
  Q->>S: subscribe 12
  S-->>Q: 12 snapshots, seq each
  Q-->>U: quotes
  loop every update
    S-->>Q: update ACME seq 1043
    Q-->>U: quote
    Note over U: keep newest per symbol
  end
  U-->>VM: one batch per tick
  Note over VM: only changed rows redraw

Flow 2 — a gap, then a tunnel.

sequenceDiagram
  participant U as Watch use case
  participant Q as Quotes repo
  participant S as Socket
  S-->>Q: update ACME seq 1045
  Note over Q: expected 1044
  Q-->>U: interrupted ACME
  Q->>S: resync ACME
  S-->>Q: snapshot ACME seq 1046
  Q-->>U: quote, live again
  Note over S: three seconds of silence
  alt reconnects
    S-->>Q: connected
    Q-->>U: interrupted all
    Q->>S: subscribe 12 again
    S-->>Q: 12 snapshots
    Q-->>U: quotes, live again
  else still offline
    Note over U: rows stay stale with their time
  end

GET  /v1/watchlist
     → { "instruments": [ { "symbol": "ACME", "name": "Acme" } ] }

WSS  /v1/quotes                         // token in the first frame
  →  { "type": "subscribe",   "symbols": ["ACME"], "maxRate": 4 }
  →  { "type": "unsubscribe", "symbols": ["ACME"] }
  →  { "type": "resync",      "symbols": ["ACME"] }
  ←  { "type": "snapshot", "symbol": "ACME", "seq": 1042,
       "last": 18240, "previousClose": 18010,
       "currency": "EUR", "time": "…" }
  ←  { "type": "update", "symbol": "ACME", "seq": 1043,
       "last": 18245, "time": "…" }
  ←  { "type": "heartbeat", "time": "…" }

• Prices in minor units with a currency, so the client never parses a decimal string or a float.
• A sequence number per symbol, and the snapshot on the same socket, so ordering is the server's promise and a gap is detectable.
• A heartbeat and maxRate. Silence means dead, not quiet. The server conflates to four a second, and the client still coalesces, because the network bunches frames.

Decision: the network rate never reaches the main actor. Card 4 coalesces; the view model sees four batches a second.

1. Card 7 receives frames on its actor. Card 6 decodes and checks sequence numbers on its own actor.
2. Card 4 writes each quote into its buffer: newest per symbol wins. An older one is overwritten.
3. On each tick, if anything changed, it emits one batch with only those symbols.
4. The view model, on the main actor, rebuilds only those rows. A tick with no changes emits nothing.

Rejected: one main-actor hop per message. Three hundred re-renders a second nobody can read. That's the hot phone.

Rejected: once per frame. Sixty or 120 updates a second is right for a chart, wrong for digits. People read a price, not an animation.

What SwiftUI redraws. @Observable tracks properties, not array elements: the list re-reads rows on each batch. Each PriceRowView is Equatable, so only changed rows run their body; fifty comparisons four times a second is nothing. If Instruments shows the list itself as hot, give each row its own small observable cell. Measure first.

Flash without layout churn. The row state carries Flash(direction, counter). A new counter starts a short tint animation behind the text. Monospaced digits and a fixed-width column mean nothing moves.

Decision: freshness is the server's sequence and heartbeat, never "the last value I have".

A gap in the numbers:

1. Card 6 expects last + 1. A smaller number is a duplicate, dropped.
2. A bigger number means updates were lost. Mark the symbol interrupted and send resync.
3. Until the new snapshot, the row shows its last price dimmed, with "12 sec ago".
4. The snapshot carries a sequence number; updates after it apply as usual.

A dead socket:

1. No frame for three seconds → dead. Close it and mark every symbol interrupted.
2. Reconnect with backoff and jitter. A token refresh first if the close said "expired".
3. On .connected, resubscribe the current set. Each symbol gets a fresh snapshot.
4. The banner says "Reconnecting" after two seconds, so a blip doesn't flicker it.

Background: on scenePhase == .background, card 7 closes the socket. iOS would suspend it anyway, and old prices are worthless. On return, steps 2–4 again; rows show stale until their snapshot lands, usually in under a second.

Rejected: an HTTP snapshot on reconnect. It arrives on another channel, so an update can land before or after it, and the client can't order them.

Decision: subscribe to what's on screen plus a few rows of margin, and let VoiceOver read on focus, not on change.

Visible-only subscriptions:

1. Rows report appearing and disappearing. The view model waits until scrolling settles (about 300 ms).
2. It starts a new watch with the visible set; the old one is cancelled.
3. Card 6 counts per symbol. A released symbol is unsubscribed only after two seconds, so a fling back doesn't unsubscribe and resubscribe.
4. A row that scrolls back in shows its cached price at once, marked stale until an update arrives.

Twelve symbols instead of fifty cuts traffic by three quarters.

VoiceOver:

• One element per row, with a label like "Acme, 182 euros 40, up 1.2 percent". The view model builds it from the same values.
• The updatesFrequently trait, so VoiceOver reads the new value when the user lingers, not on every tick.
• No announcements per price. Posting one per change would talk over everything. Announce only "Prices may be out of date" when the banner appears.
• Colour is never the only signal: an arrow and a sign go with red and green.

Failures

Production notes (short, not on the board)

• Networking: a short-lived socket token in the first frame; HTTP timeouts and safe retries.
• Battery and data: visible-only subscriptions, server-side maxRate, a slower tick in Low Power Mode, no socket in the background.
• Metrics: time to first price, reconnects per hour, gaps per hour, share of rows shown stale, main-thread hitches.

Scale, back of the envelope

symbols subscribed × updates a second × bytes a frame = bandwidth
12 × 5 × 100 B ≈ 6 KB/s ≈ 22 MB an hour on cellular
50 × 5 × 100 B ≈ 25 KB/s ≈ 90 MB an hour

Subscriptions and server conflation move the cost; the tick keeps the main actor at about 50 row updates a second, worst case.

Grow only when asked

One screen                → the view model joins list and prices
A detail screen           → a second caller of the same use case
A total in the tab bar    → a shared quote store both read
Charts                    → a frame-rate tick for that view only
FX and crypto             → a price scale per instrument, Decimal

Answer out loud first, then open.

Scope and architecture

Coalescing and the main actor

Ordering and freshness

Lifecycle, subscriptions and accessibility

Production and change

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