13 · Adding SwiftUI to a large UIKit app

• 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 "never charge twice".
• View model — the screen's brain. It owns the screen's state and hands the screen one view state.
• Coordinator — a UIKit object that owns a navigation controller and decides which screen comes next.
• Hosting controller — a UIKit view controller whose content is a SwiftUI view.
• Hosting configuration — the same idea for one table or collection cell.
• Representable — a SwiftUI view that wraps a UIKit view or view controller.
• Observation tracking — recording which properties a piece of code read, and running it again when one changes.
• Leaf screen — a screen that opens nothing else, like a detail or a settings page.

"How is navigation done today?" → Coordinators, each owning a UINavigationController. Tabs are a UITabBarController.

"What architecture inside screens?" → View controllers with view models. Some use delegates, some closures.

"Minimum OS?" → iOS 17. Swift 6. We'd like to use the newest APIs where they exist.

"What will be SwiftUI first?" → New screens. The first is a new order detail, opened from the existing UIKit order list.

"Is there a design system?" → A UIKit one: colours in an asset catalog, a type ramp, buttons.

"Rewrite allowed?" → No. We ship every two weeks.

"Anything already painful?" → The order list scrolls badly on old phones. Don't make it worse.

"Tests?" → Unit tests for view models, UI tests on the main flows.

Out of scope, said first: rewriting existing screens, changing the data layer, a new architecture pattern, the server. The repositories are reused as they are.

Required for the prompt

1. Show a SwiftUI screen from UIKit navigation, and back again.
2. Use SwiftUI rows inside existing UIKit lists.
3. Use a UIKit-only component (the receipt scanner) inside a SwiftUI screen.
4. One design system and one kind of view model for both frameworks.

What must feel good: a migrated screen looks identical · navigation feels native (back swipe, large titles) · no scroll regressions · every screen testable without UI.

Production considerations (say, don't draw): sizing, safe areas, list performance, metrics. See section 12.

Optional follow-ups (add only when asked):

A whole flow in SwiftUI     → a SwiftUI NavigationStack inside one hosting controller
State on two screens        → a shared @MainActor @Observable store
Most tabs are SwiftUI       → flip the root to a SwiftUI TabView
Deep links into SwiftUI     → the coordinator still routes them

"I'll start with a leaf screen and grow the boundary one step at a time."

"UIKit keeps the app shell and navigation for now. A coordinator pushes a UIHostingController whose root is a SwiftUI view, and hands that view closures like onOpenReceipt, so SwiftUI reports intents and never navigates. Existing lists get SwiftUI rows through UIHostingConfiguration, and the one UIKit-only component goes into SwiftUI through a representable. View models are @MainActor @Observable classes that import no UI framework, so SwiftUI observes them for free and UIKit observes them with updateProperties() on iOS 26, an Info.plist key on iOS 18, and withObservationTracking on iOS 17. The data layer and its endpoints, GET /orders and GET /orders/{id}, don't change."

Adapted for an architecture prompt: the cards are boundaries (who hosts whom, who owns what), the one-blank test applies to each, and section 8 holds the module contracts across the UIKit–SwiftUI line instead of a server contract. The server is unchanged.

Nine cards, no chips. The view models depend on the existing OrderRepository protocol; its implementation is reused.

Not drawn: the tab bar controller, the other coordinators, the row view (a plain SwiftUI view inside card 2). Not on the list yet: everything under "optional follow-ups".

flowchart TB
  subgraph U["UIKIT"]
    Coord["`**1 · Coordinator**
OrdersCoordinator
owns the stack`"]
    List["`**2 · View controller**
OrderListViewController
SwiftUI rows`"]
    Host["`**3 · Hosting controller**
UIHostingController`"]
  end
  subgraph S["SWIFTUI"]
    Detail["`**4 · View**
OrderDetailView`"]
    Scan["`**5 · Representable**
ReceiptScannerRepresentable`"]
  end
  subgraph SH["SHARED"]
    ListVM["`**6 · View model**
OrderListViewModel`"]
    DetailVM["`**7 · View model**
OrderDetailViewModel`"]
    DS["`**8 · Design system**
DesignSystem
UIColor and Color`"]
    Repo["`**9 · Repositories**
reused, unchanged
GET /orders
GET /orders/{id}`"]
  end
  Coord -- "push → list" --> List
  Coord -- "push → detail" --> Host
  Host -- "hosts → view" --> Detail
  Detail -- "embeds → scan" --> Scan
  Detail -- "actions → view state" --> DetailVM
  List -- "actions → view state" --> ListVM
  ListVM ~~~ DetailVM
  DetailVM ~~~ DS
  Detail -- "token → style" --> DS
  ListVM -- "load → orders" --> Repo
  DetailVM -- "load → order" --> Repo
  class Coord,List pres
  class Host,Scan focus
  class Detail pres
  class ListVM,DetailVM,DS dom
  class Repo reuse

How to read it. A solid arrow points from the asker or owner to the part it uses. The two bold cards are the bridges between frameworks. Navigation only ever starts in the UIKIT frame.

Dependency inversion, in one line. Both view models depend on the OrderRepository protocol, not on UIKit or SwiftUI, so either framework can draw them and the reused data layer is untouched.

No shared store on this sketch: the list and the detail each own their screen's state. If both had to show a live status, it would move into one store (section 13).

On Miro: three frames, nine cards, nine solid arrows. Point at card 3: "this is the whole boundary for a screen. SwiftUI lives inside it, UIKit owns everything around it."

The model everyone shares is the existing Order from the domain. The views never see a DTO.

1 · Orders coordinator (OrdersCoordinator)

Job: owns the orders tab's UINavigationController. It builds each screen with its view model and closures, and decides what comes next.

Interface:

@MainActor
final class OrdersCoordinator {
    init(navigation: UINavigationController, orders: OrderRepository)
    func start()
    func showDetail(_ id: OrderID)
    func showReceipt(for id: OrderID)
}

Choices:

• It keeps navigation during the migration. One owner per stack. A pushed hosting controller gets back swipe and the large title for free.
• It never imports a SwiftUI view's insides. It creates the view with a view model and closures, and wraps it.

2 · Order list (OrderListViewController)

Job: the existing UIKit list. Its rows are now SwiftUI views, set through UIHostingConfiguration on each cell.

Interface: reads viewModel.viewState in updateProperties(); forwards didSelect as viewModel.select(_:).

Choices:

• A hosting configuration per cell, never a hosting controller per cell. The configuration is built for cell reuse; a controller per cell adds child view controllers to every scroll.
• The diffable data source stays. Only the cell's content changes.

3 · Hosting controller (UIHostingController)

Job: Apple's bridge: a view controller whose view is a SwiftUI hierarchy. The coordinator pushes it like any other.

Interface:

let detail = OrderDetailView(
    viewModel: viewModel,
    onOpenReceipt: { [weak self] in self?.showReceipt(for: id) }
)
navigation.pushViewController(UIHostingController(rootView: detail), animated: true)

Choices:

• No NavigationStack inside it. The UIKit stack already owns the bar; a second stack fights it. .navigationTitle and toolbar items on the root view are forwarded to the hosting controller's navigation item, so set them in SwiftUI and check on the oldest OS.
• Size it explicitly when embedded. As a child inside a UIKit layout, set sizingOptions to .intrinsicContentSize (or .preferredContentSize for popovers and sheets).

4 · Order detail screen (OrderDetailView)

Job: draws the detail's view state, and reports taps as closures. It decides nothing, and navigates nowhere.

Interface: in section 8.

Choice: closures, not a router object, at first. One closure per exit is the smallest contract. When a screen has many exits, pass one (OrderDetailRoute) -> Void instead.

5 · Scanner representable (ReceiptScannerRepresentable)

Job: wraps the existing UIKit receipt scanner so the SwiftUI detail can show it.

Interface:

struct ReceiptScannerRepresentable: UIViewControllerRepresentable {
    /// Called on the main actor with the scanned text, once.
    let onScan: (String) -> Void
}

Choice: its coordinator is the scanner's delegate, and turns delegate calls into the closure. The representable keeps no state of its own; SwiftUI may recreate it at any time.

6 · List view model (OrderListViewModel)

Job: keeps the list's rows and loading state, as one view state.

Interface:

@MainActor @Observable
final class OrderListViewModel {
    init(orders: OrderRepository, onSelect: @escaping (OrderID) -> Void)
    var viewState: OrderListViewState { get }
    func onAppear() async
    func select(_ id: OrderID)
}

Choice: @Observable, and no UIKit or SwiftUI import. That is what lets a UIKit screen use it today and a SwiftUI screen tomorrow, unchanged.

7 · Detail view model (OrderDetailViewModel)

Job: keeps the detail's order, its load state and the scan result, as one view state.

Interface:

@MainActor @Observable
final class OrderDetailViewModel {
    init(id: OrderID, orders: OrderRepository)
    var viewState: OrderDetailViewState { get }
    func onAppear() async
    func receiptScanned(_ text: String)
}

Choices:

• Exits are not its job. The view's closures go straight to the coordinator. The view model owns the screen's state, not the stack.
• Main actor, so UIKit and SwiftUI both read it without hopping.

8 · Design system (DesignSystem)

Job: one set of colours, type and components, exposed to both frameworks.

Interface:

enum DSColor {
    /// From the shared asset catalog.
    static var accent: UIColor { get }
}
extension Color {
    /// The same token, for SwiftUI.
    static var dsAccent: Color { get }
}

Choices:

• One source, two faces. Each colour set lives once in the asset catalog. SwiftUI uses Color(uiColor:) or the same named colour, so dark mode and contrast match by construction.
• A UIKit theme reaches SwiftUI through traits. A custom trait conforming to UITraitBridgedEnvironmentKey (iOS 17) shows up in the hosted view's environment.

9 · Repositories (reused)

Job: the existing data layer, behind the existing OrderRepository protocol. Nothing about it changes.

Choice: the migration stops at the view model. That is why it is safe to do screen by screen.

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

Not added: a SwiftUI router, a shared store, a protocol per view model, a wrapper type around UIHostingController. Each waits for a requirement that needs it.

Flow 1 — tap an order in the UIKit list, see the SwiftUI detail.

sequenceDiagram
  participant L as Order list
  participant LVM as List view model
  participant C as Coordinator
  participant H as Hosting controller
  participant D as Detail view model
  L->>LVM: select(id)
  LVM->>C: onSelect(id)
  C->>D: init(id, orders)
  C->>H: rootView: OrderDetailView(viewModel, closures)
  C->>C: push the hosting controller
  H->>D: onAppear()
  alt order loaded
    D-->>H: view state, content
  else load failed
    D-->>H: view state, error with retry
  end

Flow 2 — the user scans a receipt, then opens it.

sequenceDiagram
  participant V as Detail screen
  participant S as Scanner representable
  participant D as Detail view model
  participant C as Coordinator
  V->>S: show scanner
  alt scan succeeds
    S-->>V: onScan(text)
    V->>D: receiptScanned(text)
    D-->>V: view state, receipt attached
  else user cancels
    S-->>V: dismissed, no call
  end
  V->>C: onOpenReceipt()
  C->>C: push receipt screen

SwiftUI reports intents; only the coordinator moves the stack.

The interfaces across the UIKit–SwiftUI line. These are what reviews guard.

// A SwiftUI screen's contract: a view model and its exits
struct OrderDetailView: View {
    init(
        viewModel: OrderDetailViewModel,
        /// Called on the main actor. The coordinator decides what happens.
        onOpenReceipt: @escaping () -> Void
    )
}

// The view state both frameworks render
struct OrderDetailViewState: Equatable {
    let title: String
    let status: String
    let total: String
    /// loading, loaded, failed(message)
    let load: LoadState
    let receipt: ReceiptState
}

// A screen with many exits gets one route callback instead
enum OrderDetailRoute: Hashable, Sendable {
    case receipt(OrderID)
    case support(OrderID)
}

// The data contract, unchanged
protocol OrderRepository: Sendable {
    /// Throws on failure. Cancelling the caller cancels the request.
    func order(_ id: OrderID) async throws -> Order
    func recentOrders() async throws -> [Order]
}

• The view state is plain values, formatted already, so either framework can draw it and a test can compare it.
• Exits are closures or one route enum, never a navigation controller passed into SwiftUI.
• The endpoints don't change. The repositories keep calling the same GET /v1/orders and GET /v1/orders/{id}.

Decision: UIKit coordinators own every stack until a whole tab is SwiftUI. SwiftUI screens report intents.

1. The coordinator creates the SwiftUI view with closures for each exit.
2. A tap calls the closure on the main actor. The coordinator pushes, presents or dismisses.
3. Back swipe, large titles and the tab bar keep working, because the stack is a real UINavigationController.
4. Deep links still go to coordinators, which already know how to build each screen.

A whole SwiftUI flow (a three-step return wizard) can own its own NavigationStack, inside one hosting controller that the coordinator presents modally. Never inside a pushed one: two stacks would each draw a bar.

Rejected: passing the navigation controller into SwiftUI, or reading it from the environment. The screen then knows UIKit, can't be previewed alone, and two owners move one stack.

Decision: one @MainActor @Observable view model, observed the way each OS allows.

1. SwiftUI: reading viewState in body registers the dependency. Nothing to do.
2. iOS 26: UIKit tracks @Observable reads in updateProperties(), layoutSubviews() and cell configuration handlers, and calls them again on change. Read viewState in updateProperties(); it runs before layout and doesn't force one.
3. iOS 18: the same tracking in layout methods, switched on with the UIObservationTrackingEnabled Info.plist key. updateProperties() doesn't exist yet, so read in viewWillLayoutSubviews().
4. iOS 17: wrap the read in withObservationTracking(_:onChange:). Its onChange fires once, before the value changes, and may run off the main actor, so hop to the main actor, re-read, and register again.

Hide the version split in one place: a small helper on the view controller that the list calls once. Delete the iOS 17 branch the day the minimum moves.

Rejected: a second, Combine-based view model for UIKit. Two copies of the logic drift, and the migrated screen behaves differently from the old one.

Decision: leaves first, then cells, then whole flows, then the root, one tab at a time.

1. Leaf screens: details, settings, empty states. They open nothing, so navigation is untouched.
2. Cells: SwiftUI rows in existing lists, through hosting configurations. High reuse, small risk.
3. Flows: a self-contained flow in one hosting controller with its own NavigationStack.
4. Flip a tab's root when most of its screens are SwiftUI: the tab becomes a SwiftUI NavigationStack, and the remaining UIKit screens enter through UIViewControllerRepresentable. Navigation ownership moves to SwiftUI at the same moment, never half.

Ship behind a flag. The coordinator builds either the old view controller or the hosting controller, with the same view model. Compare metrics, then delete the old one.

Rejected: flipping the app root first. Every UIKit screen then sits inside a representable, and navigation ownership splits on day one.

Failures

Production notes (short, not on the board)

• Performance: a hosting configuration's row should be a small view over plain values. Measure with the Animation Hitches instrument on the oldest phone, before and after.
• Sizing: UIHostingConfiguration self-sizes cells; set its margins instead of padding inside the row.
• Testing: view models are tested without any UI. Coordinators are tested by asserting which screen and which closures they built. UI tests keep working if migrated screens keep their accessibility identifiers.
• Metrics: screen load time, scroll hitches, crash rate per screen, the share of screens migrated.

Scale, back of the envelope, with the interviewer's numbers:

screens × share touched per release ≈ screens migrated per release
300 × 5% ≈ 15

About 15 screens a release, so a few years to finish, which is why the boundary has to be comfortable to live with.

Grow only when asked

New leaf screens          → hosting controllers pushed by coordinators
New list rows             → hosting configurations
A whole flow              → one hosting controller with its own NavigationStack
Live state on two screens → one shared @MainActor @Observable store
Most of a tab is SwiftUI  → flip that tab's root, UIKit screens via representables

Answer out loud first, then open.

Bridges

Navigation

State and observation

Design system

Migration, testing and performance

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