In Part 1, I measured my space and laid out the master plan, dealing with my 10-foot width constraint. In Part 2, I agonized over the “brains” of the operation and landed on the Square Golf launch monitor as the perfect blend of performance and value.

Now, it’s time to build the “home” for it all: the enclosure. This post will cover everything from the frame and screen to the safety padding and floor.

Choosing the impact screen

Before I could build the frame, I had to know exactly what I was stretching inside it. The screen’s dimensions and mounting system dictate the entire frame build.

After a lot of research, I landed on the Poly Spacer Impact Screen. I ordered the (8.5’ x 8.5’) model.

This screen hit all my key requirements. The “Poly Spacer” material is a premium, 2-layer screen with an internal nylon cushion. Everything I read said this material is a perfect trifecta of:

1. Durability: It’s designed to take thousands of real ball impacts.
2. Low Noise: This was a huge one for a garage build. The cushioned layers make the impact a dull, satisfying “thud” instead of a loud “CRACK.”
3. Low Bounce-Back: The material is made to absorb energy, so the ball just drops to the floor instead of firing back at me.

The biggest selling point for this DIY build, though, was the finish. It comes with a heavy-duty 3-inch black vinyl border with metal grommets already installed every 12 inches. This meant I wouldn’t have to do any sewing or complex finishing. It was built to be hung on a frame.

Building the frame

Just like with the launch monitor, my goals for the enclosure were:

1. Cost-effective: No way was I spending thousands on a pre-built frame.
2. Sturdy: It has to withstand thousands of ball impacts.
3. DIY-friendly: I needed to be able to build it myself with basic tools.

I settled on the most popular and proven method: building the frame from 1” metal conduit (EMT). It’s cheap, rigid, and available at any big-box hardware store.

Materials

• 1” EMT (Electrical Metallic Tubing) Conduit: 9 10-foot lengths.
• Metal Fittings: This is the secret sauce that makes the project so easy. Instead of trying to weld or bend pipe, I bought 6 3-way fittings and 2 2-way fittings. These are heavy-duty, galvanized steel, and have welded connections. The conduit just slides in and is secured with included eyebolts.
• Spray Paint: For a clean, professional finish i picked the Krylon paint and primer even though nothing would really be visible from the pipe.

Dimensions

The most important step was getting the dimensions right. The rule of thumb for a grommet screen is to add about 3 inches on each side for tensioning. I also settled on 5’ depth. The duct canvas (more on it later) that I was going to use for the sides comes in 5’ width so I could just cut the 10’ EMT pipes in half - it was a no brainer.

• My Screen Size: 102” x 102”
• My Frame Size: (102” + 3”) x (102” + 3”) = 105” x 105” x 60”

Assembly and finishing

1. Paint It Black: Before final assembly, I gave all the cut conduit and fittings a good couple of coats of the black spray paint. This is purely aesthetic, and it really doesn’t make any difference since the pipe would be covered.
2. Lay It Out: Once dry, I laid all my painted pipes and corner fittings on the garage floor in their final shape.
3. Assemble: I slotted the conduit pipes into the 3-way and 2-way corner fittings one by one and tightened the eyebolts.
4. Stand It Up: I stood the frame up in its final position. The result was a solid, professional-looking black frame, built for a fraction of the cost of a pre-made kit.

Hanging the screen

This is where the planning paid off. That gap on all four sides was the perfect amount of space needed for tensioning.

The installation was incredibly simple:

1. Get Bungees: I bought a box of these cheap bungee balls from Amazon.
2. Start at the Corners: I attached the four corners of the screen to the four corners of the frame first. This got the screen hanging in place.
3. Work Your Way Around: I then worked my way from the corners to the middle, one bungee at a time. I looped a bungee through every single grommet and wrapped it around the 1” conduit pipe.

The goal is to create even tension all the way around, just like a small trampoline. You want it tight enough to get a flat, wrinkle-free surface for the projector, but with just enough “give” to absorb the ball’s impact safely.

The foundation (a stroke of luck)

The enclosure was now framed but it was still standing on a cold, hard, concrete garage floor. I was budgeting for some kind of flooring, whether it was foam tiles or a large piece of turf, and it wasn’t going to be cheap but a friend of mine had a giant roll of high-quality artificial turf left over from a landscaping project. He mentioned it was just sitting around, and the best part? It was already cut to a size that was a perfect fit for my simulator bay.

The installation was, without a doubt, the easiest part of the entire build.

I just… put it down.

I unrolled it, flattened it out, and that was it. Instantly, the space was transformed. The turf deadens the sound of dropped balls, looks incredibly professional, and just feels right under your feet.

(To be clear, this isn’t my hitting mat—you’d destroy your wrists hitting off a thin piece of turf on concrete. This is the stance/flooring turf that covers the whole area. The actual hitting mat will sit on top of this.)

The result

Stepping back and seeing the screen up for the first time was a huge “wow” moment. It transformed from a pile of black pipes into an actual simulator. Hitting a few gentle test shots confirmed my choice—the sound was a dull, solid ‘thwack,’ and the ball just dropped straight down.

What’s Next?

In Part 4, I’ll walk you through some serious challenges in getting the protection layer right on all the sides.

@Environment: Reading the System’s Mind

Think of @Environment as a way for your views to read system-wide settings or values provided by the SwiftUI framework itself. It’s like asking your app, “What’s the current situation?”

You use @Environment to access values like:

• The device’s color scheme (dark or light mode)
• The current locale or calendar
• The size class (compact or regular)
• The presentation mode (for dismissing a modal view)

Key Characteristics:

• Purpose: To read data provided by the system or a parent view through the environment.
• Scope: App-wide or hierarchy-wide.
• Ownership: The view does not own this data. It’s just a subscriber to a value that exists elsewhere.
• Usage: Mostly for read-only access.

Example: Detecting Dark Mode

Let’s say you want to change a text color based on whether the user is in dark mode. @Environment makes this trivial.

import SwiftUI

struct EnvironmentDemoView: View {
    // Read the colorScheme value from the environment
    @Environment(\.colorScheme) var colorScheme

    var body: some View {
        VStack {
            Text("Hello, SwiftUI!")
                .font(.largeTitle)
                .foregroundStyle(colorScheme == .dark ? .white : .black)
                .padding()
                .background(colorScheme == .dark ? .black : .white)
                .cornerRadius(10)
                .shadow(radius: 5)

            Text(colorScheme == .dark ? "You are in Dark Mode" : "You are in Light Mode")
                .padding(.top)
        }
    }
}

#Preview {
    EnvironmentDemoView()
}

Here, \.colorScheme is a key path to the value we want to read. SwiftUI automatically updates our view whenever this environment value changes. We didn’t have to pass it down manually; the view simply plucked it out of the air.

@EnvironmentObject: The App-Wide Data Sharer

What if you have your own custom data that multiple, separate views need to access? For example, user authentication status, app settings, or a shared data model. Passing this data through every single intermediate view would be a nightmare.

This is where @EnvironmentObject shines. It allows you to inject your own custom object (a class conforming to ObservableObject) into the view hierarchy, making it available to any child view that asks for it.

Key Characteristics:

• Purpose: To share your own observable objects across a deep view hierarchy without manual dependency injection.
• Scope: Any descendant view of where the object is injected.
• Ownership: The view that declares @EnvironmentObject does not own the object. It assumes the object has been created and placed in the environment by an ancestor view.
• Usage: For shared app state that many views need to read and modify.

Example: Sharing User Settings

Create the Observable Object:

import SwiftUI

class UserSettings: ObservableObject {
    @Published var username: String = "Guest"
    @Published var isAuthenticated: Bool = false
}

Inject the Object in a Parent View: You create an instance of your object and inject it into the environment using the .environmentObject() modifier. A common place to do this is at the root of your app.

import SwiftUI

@main
struct MyApp: App {
    // Create the single source of truth for user settings
    @StateObject private var settings = UserSettings()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(settings) // Inject it here!
        }
    }
}

Access it in any Child View: Now, any view inside ContentView can easily access UserSettings.

struct ProfileView: View {
    // Ask for the UserSettings object from the environment
    @EnvironmentObject var settings: UserSettings

    var body: some View {
        VStack {
            Text("Welcome, \(settings.username)!")
            if settings.isAuthenticated {
                Button("Log Out") {
                    settings.isAuthenticated = false
                    settings.username = "Guest"
                }
            }
        }
    }
}

Notice we didn’t have to pass settings into ProfileView. It just works! Warning: If you forget to inject the object with .environmentObject(), your app will crash when the view tries to access it.

@StateObject: The Owner and Creator

So, if @EnvironmentObject is for receiving shared data, where is that data created? In our example above, we used @StateObject.

@StateObject is the property wrapper you use to instantiate and manage the lifecycle of an observable object within a specific view. SwiftUI ensures that an object declared as a @StateObject is created only once for the lifetime of that view. Even if the view’s struct is re-created during a redraw, the @StateObject persists.

Key Characteristics:

• Purpose: To create and own an instance of an observable object. This view is the source of truth for that object.
• Scope: The view that declares it.
• Ownership: The view owns the object. It’s responsible for its creation and destruction.
• Usage: Use it when a view needs its own persistent, complex state that can be shared with subviews (often via @ObservedObject or bindings).

Example: A View-Specific ViewModel

Imagine a view that fetches and displays a list of items. This view needs a view model to handle the network request and the resulting data. This view model belongs exclusively to this view.

import SwiftUI

class ItemListViewModel: ObservableObject {
    @Published var items: [String] = []
    @Published var isLoading = false

    func fetchItems() {
        isLoading = true
        // Simulate a network request
        DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
            self.items = ["Apple", "Banana", "Cherry"]
            self.isLoading = false
        }
    }
}

struct ItemListView: View {
    // This view creates and OWNS its view model.
    @StateObject private var viewModel = ItemListViewModel()

    var body: some View {
        VStack {
            if viewModel.isLoading {
                ProgressView()
            } else {
                List(viewModel.items, id: \.self) { item in
                    Text(item)
                }
            }
        }
        .onAppear {
            viewModel.fetchItems()
        }
    }
}

Here, ItemListView is the definitive owner of its viewModel. The viewModel will not be accidentally deallocated or re-created during view updates.

Summary: At a Glance

Conclusion

Understanding the difference between these three property wrappers is fundamental to architecting a clean and scalable SwiftUI application.

• Use @Environment to peek at the system’s state.
• Use @StateObject to create and own your object in one specific view.
• Use @EnvironmentObject to receive that object in any other view, no matter how far down the hierarchy it is.

Happy coding!

• Background
• The Plan: A Modern Approach
  • Step 1: Laying the Foundation
  • Step 2: Creating the Diffable Data Source
  • Step 3: Tying it to Core Data
  • Step 4: The Initial Load
• The Result: Cleaner, Simpler Code
• Conclusion

Background

To recap, the PhotoListController was using a NSFetchedResultsController to manage photos from Core Data. The delegate methods were responsible for updating the UICollectionView in response to data changes. This involved a lot of manual work with BlockOperation to batch updates, which, as I discovered in Part 1, can be tricky to get right.

The goal of this refactoring was to simplify this process by leveraging UICollectionViewDiffableDataSource, which Apple introduced in iOS 13. Diffable data sources automatically handle the complexities of updating the UI, which means less code, fewer bugs, and a happier developer (me).

The Plan: A Modern Approach

The plan was to replace the existing UICollectionViewDataSource and NSFetchedResultsControllerDelegate methods with a UICollectionViewDiffableDataSource. Here’s how I broke it down.

Step 1: Laying the Foundation

First, I needed to define the section and item identifiers for the diffable data source. Since my collection view only has one section, this was straightforward. The item identifier would be the Photo object itself, because the NSManagedObject it inherits from already conforms to Hashable.

// In PhotoListController.swift

enum Section {
    case main
}

Step 2: Creating the Diffable Data Source

Next, I created a new property for the UICollectionViewDiffableDataSource in PhotoListController.swift.

// In PhotoListController.swift

private var dataSource: UICollectionViewDiffableDataSource<Section, Photo>!

Then, in viewDidLoad, I configured the data source. This involved creating the data source and providing a “cell provider” closure, which is responsible for configuring and returning a cell for a given IndexPath and Photo.

// In PhotoListController.swift, inside viewDidLoad()

dataSource = UICollectionViewDiffableDataSource<Section, Photo>(collectionView: collectionView!) {
    (collectionView: UICollectionView, indexPath: IndexPath, photo: Photo) -> UICollectionViewCell? in
    let cell = collectionView.dequeueReusableCell(withReuseIdentifier: PhotoCell.reuseIdentifer, for: indexPath) as! PhotoCell
    if let data = photo.thumbnailImage?.imageData as Data?, let image = UIImage(data: data) {
        cell.imageView.image = image
    }
    return cell
}

This code replaces the old collectionView(_:cellForItemAt:) method.

Step 3: Tying it to Core Data

This is where the magic happens. The NSFetchedResultsControllerDelegate methods were significantly simplified. Instead of manually managing BlockOperations, I just needed to create a new snapshot of the data and apply it to the data source in the controller(_:didChangeContentWith:) method.

// In PhotoListController+NSFetchedResultsControllerDelegate.swift

func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>, didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference) {
    guard let dataSource = self.dataSource else { return }

    var newSnapshot = NSDiffableDataSourceSnapshot<Section, Photo>()
    newSnapshot.appendSections([.main])
    newSnapshot.appendItems(controller.fetchedObjects as? [Photo] ?? [])

    dataSource.apply(newSnapshot, animatingDifferences: true)

    // Refresh empty state and other UI elements
    self.collectionView?.reloadEmptyDataSet()
    self.editButtonItem.isEnabled = controller.fetchedObjects?.count != 0
    if (controller.fetchedObjects == nil || controller.fetchedObjects?.count == 0) {
        self.setEditing(false, animated: true)
    }
}

With this change, I was able to remove the old controllerWillChangeContent, controller(_:didChange:at:for:newIndexPath:), and controllerDidChangeContent methods. A huge simplification!

Step 4: The Initial Load

Finally, I updated the initial data load in viewDidLoad. After performing the initial fetch, I just needed to call a helper function to update the data source with the fetched data.

// In PhotoListController.swift, inside viewDidLoad()

// Fetch data
do {
    try self.fetchedResultsController.performFetch()
    updateDataSource()
    self.editButtonItem.isEnabled = fetchedResultsController.fetchedObjects?.count != 0
} catch {
    fatalError("Error fetching photos: \(error)")
}

// new helper function
private func updateDataSource() {
    var snapshot = NSDiffableDataSourceSnapshot<Section, Photo>()
    snapshot.appendSections([.main])
    snapshot.appendItems(fetchedResultsController.fetchedObjects ?? [])
    dataSource.apply(snapshot, animatingDifferences: false)
}

The Result: Cleaner, Simpler Code

After the refactoring, the PhotoListController is much cleaner and easier to understand. The NSFetchedResultsControllerDelegate extension is now tiny, and I was able to delete a lot of the old, complex code for managing collection view updates.

The drag-and-drop functionality still works perfectly, but now it’s built on a much more robust and modern foundation.

Conclusion

This refactoring was a great investment. It not only modernized the codebase but also made it more resilient to bugs and helped me eliminate a ton of code and unit tests. If you’re still using the old NSFetchedResultsControllerDelegate with UICollectionView, I highly recommend looking into UICollectionViewDiffableDataSource. It’s a game-changer.

I hope this two-part series has been helpful. If you have any questions or feedback, feel free to reach out!

My Shortlist

I started by comparing some of the most popular options using these criteria:

1. Space Requirements – The deal-breaker for my narrow setup.
2. Left/Right-Hand Support – Ideally without physically moving the monitor.
3. Cost – Definitely cannot break the bank.
4. Software Compatibility – Flexibility to try different virtual courses but best without paid subscriptions.
5. Club Face Data Accuracy – Nice to have real measurements, not estimates.

Before diving into specs, let me talk briefly about the core technology, because my garage 10’ width immediately splits the field in half.

• Radar (Doppler) Units: These sit behind the golfer (R10, MLM2PRO, Mevo+). They need a clear view of the ball traveling forward. In a narrow space, I have to use an “offset” hitting position (not centered) to have enough room to swing. This can make it difficult for a radar unit to get a perfectly straight-on view, potentially affecting accuracy. They also require more room depth to track the ball.
• Photometric (Camera) Units: These sit to the side of the golfer (Square Golf, SkyTrak+, Bushnell LP) or are mounted to the ceiling (Uneekor). They don’t care where I stand in the room, as long as they are positioned correctly next to the ball. This makes them ideal for my offset setup and for spaces with less depth.

Stage 1 Elimination: Why Radar is a No-Go

My first decision was easy. I have eliminated all radar-based launch monitors from consideration. This includes popular units like the Garmin R10, Rapsodo MLM2PRO, and FlightScope Mevo+.

The reason is simple: Radar units need to sit directly behind the ball to work accurately. In my narrow 10’-wide garage, I must use a dual “offset” hitting position (not centered) to have enough room to swing a driver. The radar units seem to work best when centered and although there is some support for offset, there is absolutely no support that I could find for dual offset to accomodate both lefties and righties. In my opinion this is a huge missed opportunity as I really liked the Mevo+ as far as overall package.

Stage 2 Elimination: The “Dream vs. Reality” Check

With my search narrowed to camera systems, I looked at the absolute best solution for my space: an overhead launch monitor.

Units like the Uneekor EYE MINI (which can be floor-based or overhead) and the Uneekor QED or EYE XO are the “dream setup” for a space like mine. They mount to the ceiling, perfectly out of the way. Their biggest advantage is that they provide seamless support for both right- and left-handed players. There’s no need to move any equipment; friends can switch from righty to lefty on the fly. This was a huge selling point for me.

So why aren’t I buying one? In a word: cost.

These professional-grade overhead systems start at around $4,500 and go up to $10,000 and beyond. As amazing as they are, a $5,000+ price tag for the launch monitor alone is outside the budget for my value-focused DIY build. So, with a heavy heart, I had to set the “dream setup” aside. This project is about creating the best possible experience for a realistic price.

This left me with a final showdown between the three most compelling side-placed camera units on the market.

The Final Contenders:

• The Budget Disruptor: Square Golf
• The Established All-Rounder: SkyTrak+
• The Professional-Grade Benchmark: Bushnell Launch Pro

The Final Showdown: Head-to-Head Comparison

Each of these units sits beside the golfer, making them a great fit for my space. Now it’s a battle of performance, features, and the total cost of ownership.

Breaking It Down: What Really Matters?

With the “perfect” overhead solution off the table, my decision comes down to which compromises I’m willing to make with a floor unit.

Data Quality & Accuracy

All three provide the measured data I want, but to varying degrees of precision.

• Bushnell Launch Pro: The king of raw ball data accuracy. It’s as close to tour-level as you can get, but you have to pay a premium subscription to unlock its club data capabilities.
• SkyTrak+: A powerful all-around performer with excellent accuracy on both ball and club data right out of the box.
• Square Golf: The value champion. It provides the essential measured club data I want, and while it might not be as precise as the other two, it’s a massive leap over any estimated data.

My Take: The data from all three is excellent for my needs. The extra precision of the premium units is nice, but I question if it’s worth a 5x to 6x increase in long-term cost.

The Real Cost: Software & Subscriptions

This is where the choice becomes crystal clear. My goal is to play GSPro software without being chained to expensive annual fees just to connect.

• Bushnell Launch Pro & SkyTrak+: These are built on the subscription model. To get the features I want and connect to GSPro, I’d be paying hundreds of dollars every year, forever. Over just a few years, the cost of the software subscription would be more than the entire price of the Square Golf unit.
• Square Golf: The hero of the DIY builder. It has a policy of no extra fees to connect to GSPro. The price on the box is the real price to get up and running with the best community software. I can also go and buy Awesome Golf for couple hundred bucks and play for quite a while before I even get a GSPro subscription.

My Take: This isn’t just a feature; it’s a philosophy. The Square Golf model respects the customer, while the others feel designed to maximize recurring revenue.

The Final Decision

My decision-making funnel was clear:

1. Space limitations eliminated all radar units.
2. Budget limitations eliminated the “dream” overhead units.
3. This left a three-way battle of floor units, where the long-term cost became the deciding factor.

My Decision: I ordered the Square Golf launch monitor.

After considering the absolute best-case scenario (an overhead unit) and ruling it out on price, the choice became easy. The Square Golf provides the essential features of the far more expensive camera units — a side placement perfect for my space and measured club data for real game improvement — but it does so without the punitive subscription model.

The ability to connect to GSPro for free makes the total cost of ownership incredibly low and aligns perfectly with the spirit of a DIY project. I will have to live with the minor inconvenience of moving the unit for my righty friends, but that is a tiny price to pay to save literally thousands of dollars over the next few years. That savings is what will allow me to build a truly awesome simulator enclosure without breaking the bank.

What’s Next?

With the brains of my operation chosen after a long and thorough search, it’s time to build its home. In Part 3: Asembling the enclosure, I’ll take you through the entire process of designing and building the enclosure—from constructing the frame to selecting the perfect impact screen.

This isn’t just about buying a kit and plugging it in. This is about my research, my planning, the inevitable challenges, and the satisfaction of hitting that first perfect shot in a space I built myself. In this series, I’ll cover everything from choosing the right launch monitor to building the enclosure and dialing in the software.

But before I buy a single piece of equipment, it all starts with a plan.

Building a golf simulator is a project of passion, but a successful one is built on a foundation of careful planning. Rushing into purchases without a clear design is the fastest way to blow a budget and still end up with a setup that doesn’t work. So, in this first post, I’m focusing on the blueprint and the absolute non-negotiables. These are the fundamentals I have to address for myself before I even think about adding a single item to my shopping cart.

How much room do I really have?

This is the number one, non-negotiable starting point. My project will be built in a standard single-car garage stall. I’m lucky to have a spare bay in my tandem garage, but it comes with its own set of very specific dimensions.

After breaking out the tape measure, here’s what I’m working with and what it means for my build.

My dimensions are: 10' width × 12′ height × 21` depth.

Let’s break down what each of these means:

• Height (12′): This is a huge win. My ceiling height is a fantastic 12′. In the world of DIY golf simulators, this is a major luxury. It means I have zero concerns about even my tallest friends swinging a driver and hitting the ceiling. This height also gives me a ton of flexibility for mounting my projector high up and out of the way.

• Depth (20′): This is another strong point for my space. With 20′ of depth, I have plenty of room to create a safe and functional layout. I can have a 1’ behind the impact screen for damage control and pretty much any distance I need for the tee spot or the launch monitor.

• Width (10′): Now for my biggest constraint. The width of the garage stall is exactly 10′. This is widely considered the minimum viable width for a simulator, and it forces some very important decisions right from the start. With only 10′ from wall to wall, I can’t realistically center the hitting area. There simply wouldn’t be enough room for a full, confident swing on both sides of the ball without fear of hitting the side walls. This immediately confirmed that I must build an “offset” simulator. I’ll have to push the hitting area to one side of the garage stall to maximize the swing space for a single player orientation. This realization leads directly to the next big question…

Righty, lefty, or both?

This might seem like a small detail, but it has a huge impact on the project since I am a lefty and almost all of my friends are righties. Based on the width constraint above, I have to offset the tee. However, if I want to have friends and family over - I’ll likely have both right- and left-handed players. This means I must actually have dual offset and a tee spot on each side. It also means I will need a launch monitor that can accomdate the dual offset.

Let’s talk budget

A golf simulator can cost anywhere from a few thousand dollars to the price of a luxury car. It was crucial for me to set a realistic budget from the start.

I’ve broken my budget into the following core components:

1. Launch monitor & software: The brains of the operation.
2. Enclosure & screen: The physical structure.
3. Projector & PC: The visuals.
4. Mat & flooring: The foundation.
5. Climate, lighting and seating: Creature comfort.
6. Final touches

My budget for this is extremely low so I’m hoping to allocate it carefully across these categories and to provide a detailed breakdown at the end. I know that the dual offset requirement will affect the cost so if it becomes too much - it might be time for early eject.

What’s next?

Now that I have a blueprint, the real fun begins. In the next post, I’ll dive deep into Part 2: Launch Monitor & Software. I decided to focus on this first because given the non-negotiables above, there is a high probability that I either price myself out or even worse - not be able to find one at all.

This is going to be an incredible project. I hope you’ll join me on this journey, and feel free to drop your own questions and plans in the comments below!

• Background
• Plan
  • Step 1: Updating the model
  • Step 2: Adding Drag-and-Drop Support
  • Step 3: Assigning displayOrder to New Photos
• Problem
• Root cause analysis
• Solution
• Conclusion

Background

Since this is a Core Data-enabled application, the PhotoListController is a UICollectionViewController and also acts as a delegate for an NSFetchedResultsController. It retrieves photos and displays them in a 3-column grid using UICollectionViewDelegateFlowLayout. By default, photos are sorted by the date/time they were captured or imported. The controller also handles capture/import, selection, deletion, and exporting, all of which needed to be considered.

The controller’s structure is typical:

class PhotoListController: UICollectionViewController {
    lazy var fetchedResultsController: NSFetchedResultsController<Photo> = {
        let predicate = NSPredicate(format: "gun == %@", self.gun)
        let sortDescriptor = NSSortDescriptor(key: "createdOn", ascending: true)
        let fReq: NSFetchRequest<Photo> = Photo.fetchRequest()
        fReq.sortDescriptors = [sortDescriptor]
        fReq.predicate = predicate
        let frc = NSFetchedResultsController(fetchRequest: fReq, managedObjectContext: self.managedObjectContext, sectionNameKeyPath: nil, cacheName: nil)
        return frc
    }()
    // More code here...
}

The NSFetchedResultsControllerDelegate implementation uses block operations and branching logic for different update types:

extension PhotoListController: NSFetchedResultsControllerDelegate {
    func controllerWillChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
        self.blockOperations.removeAll(keepingCapacity: false)
    }
    // ...section change handling...
    func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>, didChange anObject: Any, at indexPath: IndexPath?, for type: NSFetchedResultsChangeType, newIndexPath: IndexPath?) {
        // ...insert, update, move, delete logic...
    }
    func controllerDidChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
        collectionView!.performBatchUpdates({
            for operation in self.blockOperations {
                operation.start()
            }
        }, completion: { _ in
            self.blockOperations.removeAll(keepingCapacity: false)
            // Additional logic
        })
    }
}

The model is straightforward, with UUID support from the start:

@objc(Photo)
class Photo: NSManagedObject {}

extension Photo {
    @nonobjc class func fetchRequest() -> NSFetchRequest<Photo> {
        return NSFetchRequest<Photo>(entityName: "Photo")
    }
    override func awakeFromInsert() {
        super.awakeFromInsert()
        uniqueId = NSUUID().uuidString
        createdOn = NSDate()
    }
    @NSManaged var uniqueId: String?
    @NSManaged var createdOn: NSDate?
    @NSManaged var gun: Gun?
    @NSManaged var thumbnailImage: PhotoImageThumbnail?
    @NSManaged var fullSizeImage: PhotoImageFullSize?
}

Plan

My plan was to add a custom order property to the model, enable drag-and-drop in the UICollectionViewController, and persist the new order in Core Data. Any changes would be broadcast using the existing plumbing between Core Data and the various NSFetchedResultsController delegates.

Step 1: Updating the model

To persist custom order, I introduced a new attribute displayOrder:

1. Update the model version: I generated a new model version for seamless migration.
2. Update the Photo entity: Added a new attribute displayOrder (type: Integer 16) to the Photo entity.
3. Update the Swift class: Added the displayOrder property to the Swift class.

extension Photo {
    @nonobjc class func fetchRequest() -> NSFetchRequest<Photo> {
        return NSFetchRequest<Photo>(entityName: "Photo")
    }
    override func awakeFromInsert() {
        super.awakeFromInsert()
        uniqueId = NSUUID().uuidString
        createdOn = NSDate()
    }
    @NSManaged var uniqueId: String?
    @NSManaged var createdOn: NSDate?
    @NSManaged var displayOrder: Int16 // New attribute
    @NSManaged var gun: Gun?
    @NSManaged var thumbnailImage: PhotoImageThumbnail?
    @NSManaged var fullSizeImage: PhotoImageFullSize?
}

Step 2: Adding Drag-and-Drop Support

To enable reordering, I modified the controller to implement UICollectionViewDragDelegate and UICollectionViewDropDelegate:

Enable Drag and Drop: In viewDidLoad, enable drag interactions and set delegates.

override func viewDidLoad() {
    super.viewDidLoad()
    // ...existing setup...
    collectionView.dragInteractionEnabled = true
    collectionView.dragDelegate = self
    collectionView.dropDelegate = self
}

Update Fetch Request: Sort photos by displayOrder.

lazy var fetchedResultsController: NSFetchedResultsController<Photo> = {
    let fetchRequest: NSFetchRequest<Photo> = Photo.fetchRequest()
    fetchRequest.predicate = NSPredicate(format: "gun = %@", self.gun)
    let sortDescriptor = NSSortDescriptor(key: "displayOrder", ascending: true)
    fetchRequest.sortDescriptors = [sortDescriptor]
    // ...rest of initialization...
    return frc
}()

Implement Drag Delegate: Specify draggable items.

extension PhotoListController: UICollectionViewDragDelegate {
    func collectionView(_ collectionView: UICollectionView, itemsForBeginning session: UIDragSession, at indexPath: IndexPath) -> [UIDragItem] {
        let photo = fetchedResultsController.object(at: indexPath)
        let itemProvider = NSItemProvider(object: photo.uniqueId! as NSString)
        let dragItem = UIDragItem(itemProvider: itemProvider)
        dragItem.localObject = photo
        return [dragItem]
    }
}

Implement Drop Delegate: Handle drop and persist new order.

extension PhotoListController: UICollectionViewDropDelegate {
    func collectionView(_ collectionView: UICollectionView, canHandle session: UIDropSession) -> Bool {
        return session.canLoadObjects(ofClass: NSString.self)
    }
    func collectionView(_ collectionView: UICollectionView, dropSessionDidUpdate session: UIDropSession, withDestinationIndexPath destinationIndexPath: IndexPath?) -> UICollectionViewDropProposal {
        if collectionView.hasActiveDrag {
            return UICollectionViewDropProposal(operation: .move, intent: .insertAtDestinationIndexPath)
        }
        return UICollectionViewDropProposal(operation: .forbidden)
    }
    func collectionView(_ collectionView: UICollectionView, performDropWith coordinator: UICollectionViewDropCoordinator) {
        guard let destinationIndexPath = coordinator.destinationIndexPath,
              let sourceIndexPath = coordinator.items.first?.sourceIndexPath else { return }
        guard var photos = fetchedResultsController.fetchedObjects else { return }
        let photoToMove = photos.remove(at: sourceIndexPath.item)
        photos.insert(photoToMove, at: destinationIndexPath.item)
        for (index, photo) in photos.enumerated() {
            photo.displayOrder = Int16(index)
        }
        do {
            try self.managedObjectContext.save()
        } catch {
            print("Failed to save photo order: \(error)")
        }
    }
}

Step 3: Assigning displayOrder to New Photos

I updated the capture/import logic to assign displayOrder automatically:

func imagePickerController(_ picker: UIImagePickerController, didFinishPickingMediaWithInfo info: [UIImagePickerController.InfoKey : Any]) {
    // ...existing code to get image...
    let photo = Photo(context: coreDataStack.managedContext)
    photo.uuid = UUID()
    photo.createdAt = Date()
    photo.gun = self.gun
    // Assign the next display order
    let currentCount = fetchedResultsController.fetchedObjects?.count ?? 0
    photo.displayOrder = Int16(currentCount)
    // ...rest of the method to set images and save...
    dismiss(animated: true)
}

Problem

After implementing drag-and-drop, the app crashed with the dreaded attempt to perform an insert and a move to the same index path error.

Root Cause Analysis

The issue stemmed from how NSFetchedResultsControllerDelegate interprets changes. If a move is treated as a delete and an insert, and the insert targets the same index path as another independent insert, a conflict occurs.

Solution

I modified the logic to ensure that inserts, deletes, and move targets are distinct within a batch update. Instead of using the combined move operation, I replaced it with a delete at the old index path and an insert at the new index path:

extension PhotoListController: NSFetchedResultsControllerDelegate {
    // ...other logic...
    func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>, didChange anObject: Any, at indexPath: IndexPath?, for type: NSFetchedResultsChangeType, newIndexPath: IndexPath?) {
        if type == .insert {
            blockOperations.append(BlockOperation { [weak self] in
                self?.collectionView?.insertItems(at: [newIndexPath!])
            })
        } else if type == .update {
            blockOperations.append(BlockOperation { [weak self] in
                self?.collectionView?.reloadItems(at: [indexPath!])
            })
        } else if type == .move {
            blockOperations.append(BlockOperation { [weak self] in
                guard let indexPath = indexPath, let newIndexPath = newIndexPath else { return }
                self?.collectionView?.deleteItems(at: [indexPath])
                self?.collectionView?.insertItems(at: [newIndexPath])
            })
        } else if type == .delete {
            blockOperations.append(BlockOperation { [weak self] in
                self?.collectionView?.deleteItems(at: [indexPath!])
            })
        }
    }
}

Conclusion

With these changes, I had a shippable version. Despite a lengthy debugging session, the refactor was fairly straightforward. The original code, written in 2018, was still in good shape but Apple had since introduced Diffable Data Sources, which would’ve been my go-to for a new project. In a corporate setting, such a refactor of “legacy code” would be considered technical debt and require prioritization and analysis. In my case, I just started a new branch and experimented. More on that in Part 2.

• Data model
• Workflow
• Implementation
• Problem
• Solution
• Conclusion

Data model

Before diving into the details, it is worth talking about the data I am dealing with. This is an abbreviated entity diagram that shows some of it. Each Gun instance is a parent and it has multiple child attributes: Make, Caliber, Action, Finish, Type, etc. Obviusly a Gun can only have one Type but a Type can be associated with multiple Gun objects. The attributes themselves have just one user-entered property: Name.

   erDiagram
         Gun {
             NSDate manufactureDate
             String model
             String note
            String serialNumber
        }
        GunMake {
            String name
        }
        GunCaliber {
            String name
        }
        GunAction {
            String name
        }
        GunFinish {
            String name
        }
        GunType {
            String name
        }
        Gun }o--|| GunMake : "make"
        Gun }o--|| GunCaliber : "caliber"
        Gun }o--|| GunAction : "action"
        Gun }o--|| GunFinish : "finish"
        Gun }o--|| GunType : "type"

I am very well aware that there are better ways to organize parent-child attributes but given the current context and in the spirit of KISS - this entity structure is sufficient and if need be - it can be migrated later to something better.

Workflow

For the Gun-upserting workflow I started with a very basic approach. I settled on using a table view with all the Gun attributes shown in individual cells. Once a cell is selected eg. Type - another view would present itself with a Type list to pick from and a button to add a new one needed. The new Type entry screen is even simpler - just a single textbox to collect name of the Type attribute.

Implementation

Although this is absolutely not a streamlined way of doing data entry - it has the benefit of being quick and easy to develop. A GunUpsertController, a GunTypeEditController, a DBStringEditController (not shown) along with some Core Data child branching logic to support cancellation was all that was needed.

Note: this is partial implementation for brevity.

class GunUpsertController: UITableViewController {

    var gun: Gun!
    var managedObjectContext: NSManagedObjectContext!

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {

        let result: UITableViewCell = UITableViewCell(style: .value1, reuseIdentifier: "gunType")
        result.accessoryType = .disclosureIndicator

        if indexPath.section == 0 {
            if indexPath.row == 0 { // Type
                result.textLabel?.text = Strings.LABEL_GUN_TYPE
                result.detailTextLabel?.text = gun.type?.name
            }
        }
        return result
    }


    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {

        if indexPath.section == 0 {
            if indexPath.row == 0 { // Type
                let controller = DBGunTypeEditController(gun: gun)
                controller.editPropertyControllerDelegate = self
                let navigationController = UINavigationController(rootViewController: controller)
                present(navigationController, animated: true, completion: nil)
            }
        }
    }

}

class DBGunTypeEditController: UITableViewController {

    var gun: Gun!

    var managedObjectContext: NSManagedObjectContext!

    var editPropertyControllerDelegate: DBEditPropertyControllerDelegate?

    var validationHelper: ValidationHelper!

    lazy var fetchedResultsControler: NSFetchedResultsController<GunType> = {
        [unowned self] in
        let sortDescriptor = NSSortDescriptor(key: "name", ascending: true)

        let fReq: NSFetchRequest = GunType.fetchRequest()
        fReq.sortDescriptors = [sortDescriptor]

        let frc = NSFetchedResultsController(fetchRequest: fReq, managedObjectContext: self.managedObjectContext, sectionNameKeyPath: nil, cacheName: nil)

        return frc
        }()

    convenience init(gun: Gun) {
        self.init(style: UITableViewStyle.grouped)
        self.managedObjectContext = gun.managedObjectContext
        self.gun = gun
        self.validationHelper = ValidationHelper.sharedInstance
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        self.tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")

        let cancelButton = UIBarButtonItem(barButtonSystemItem: .cancel, target: self, action: #selector(cancelButtonTapped(sender:)))
        navigationItem.leftBarButtonItem = cancelButton

        let addBarButton = UIBarButtonItem(barButtonSystemItem: .add, target: self, action: #selector(addButtonTapped(sender:)))
        navigationItem.rightBarButtonItem = addBarButton

        navigationItem.title = Strings.TITLE_SELECT_GUN_TYPE

        fetchedResultsControler.delegate = self

        do {

            try fetchedResultsControler.performFetch()

        } catch {
            fatalError("Error fetching guns: \(error)")
        }

    }

    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {

        return fetchedResultsControler.sections![section].numberOfObjects

    }

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {

        guard let result = tableView.dequeueReusableCell(withIdentifier: "cell") else {
            return UITableViewCell()
        }

        let entity = fetchedResultsControler.object(at: indexPath)

        result.accessoryType = .disclosureIndicator
        result.textLabel?.text = entity.name

        return result

    }

    override func tableView(_ tableView: UITableView, titleForHeaderInSection section: Int) -> String? {

        if let fetchedObjects = fetchedResultsControler.fetchedObjects {
            if section == 0 && fetchedObjects.count > 0 {
                return Strings.MESSAGE_EDIT_GUN_TYPE_INSTRUCTIONS
            }
        }

        return nil

    }

    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {

        let selectedEntity = fetchedResultsControler.object(at: indexPath)

        gun.type = selectedEntity
        selectedEntity.addToGuns(gun)

        editPropertyControllerDelegate?.controllerDidFinish(self)

    }

    @objc func addButtonTapped(sender: UIBarButtonItem) {

        let childContext = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
        childContext.parent = managedObjectContext
        let childEntity = GunType(context: childContext)

        let controller: DBStringEditController = DBStringEditController(managedObject: childEntity, forKey: "name")
        controller.delegate = self
        controller.navigationItem.title = Strings.TITLE_NEW_GUN_TYPE
        controller.textField.placeholder = Strings.LABEL_NAME
        let navigationController: UINavigationController = UINavigationController(rootViewController: controller)

        present(navigationController, animated: true, completion: nil)

    }

    @objc func cancelButtonTapped(sender: UIBarButtonItem) {

        editPropertyControllerDelegate?.contorllerDidCancel(self)

    }
}

Problem

Obviously a gun has more than one attribute so I quickly replicated the code to add support for Action and Caliber. Unfortunately, I still had to account for Make and Type and I also wanted to add another module later for maintaining an Ammo inventory that would follow the same workflow so it was time to honor the Rule of three and refactor before things get out of control.

Solution

The solution was to apply the Don’t Repeat Yourself (DRY) principle by abstracting the common code into basic reusable classes.

The core logic in each replicated controller was responsible for:

1. Setting up a UITableView.
2. Configuring an NSFetchedResultsController to fetch and display a lookup dataset from Core Data.
3. Handling table view updates via the NSFetchedResultsControllerDelegate.
4. Implementing DZNEmptyDataSetSource and DZNEmptyDataSetDelegate to show a user-friendly message when the table was empty.
5. Adding a “plus” button to the navigation bar to create a new entry.
6. Implementing the swipe-to-delete functionality.

I decided to create a generic DBEntityPropertyEditController.

class DBEntityPropertyEditController<T: NSManagedObject>: UITableViewController, NSFetchedResultsControllerDelegate, DZNEmptyDataSetSource, DZNEmptyDataSetDelegate, DBEditPropertyControllerDelegate {

    var parentObject: NSManagedObject!
    var managedObjectContext: NSManagedObjectContext!
    var editPropertyControllerDelegate: DBEditPropertyControllerDelegate?
    var validationHelper: ValidationHelper!

    var propertyEntityName: String!
    var navigationItemTitle: String!
    var addNewTitle: String!
    var instructionsText: String!
    var parentRelationshipKeyPath: String!
    var propertyInverseRelationshipKeyPath: String!

    lazy var fetchedResultsControler: NSFetchedResultsController<T> = {
        [unowned self] in
        let sortDescriptor = NSSortDescriptor(key: "name", ascending: true)

        let fReq: NSFetchRequest<T> = NSFetchRequest<T>(entityName: self.propertyEntityName)
        fReq.sortDescriptors = [sortDescriptor]

        let frc = NSFetchedResultsController(fetchRequest: fReq, managedObjectContext: self.managedObjectContext, sectionNameKeyPath: nil, cacheName: nil)

        return frc
    }()


    convenience init(
        parentObject: NSManagedObject,
        propertyEntityName: String,
        navigationItemTitle: String,
        addNewTitle: String,
        instructionsText: String,
        parentRelationshipKeyPath: String,
        propertyInverseRelationshipKeyPath: String
    ) {
        self.init(style: UITableView.Style.grouped)
        self.managedObjectContext = parentObject.managedObjectContext
        self.parentObject = parentObject
        self.validationHelper = ValidationHelper.sharedInstance
        self.propertyEntityName = propertyEntityName
        self.navigationItemTitle = navigationItemTitle
        self.addNewTitle = addNewTitle
        self.instructionsText = instructionsText
        self.parentRelationshipKeyPath = parentRelationshipKeyPath
        self.propertyInverseRelationshipKeyPath = propertyInverseRelationshipKeyPath
    }

    override func viewDidLoad() {
        super.viewDidLoad()

        self.tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")
        self.tableView.emptyDataSetSource = self
        self.tableView.emptyDataSetDelegate = self

        let cancelButton = UIBarButtonItem(barButtonSystemItem: .cancel, target: self, action: #selector(cancelButtonTapped(sender:)))
        navigationItem.leftBarButtonItem = cancelButton

        let addBarButton = UIBarButtonItem(barButtonSystemItem: .add, target: self, action: #selector(addButtonTapped(sender:)))
        navigationItem.rightBarButtonItem = addBarButton

        navigationItem.title = navigationItemTitle

        fetchedResultsControler.delegate = self

        do {
            try fetchedResultsControler.performFetch()
        } catch {
            fatalError("Error fetching: \(error)")
        }
    }

    // MARK: - UITableViewDataSource

    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        guard let sectionInfo = fetchedResultsControler.sections?[section] else  { fatalError("failed to resolve FRC") }
        return sectionInfo.numberOfObjects
    }

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        guard let result = tableView.dequeueReusableCell(withIdentifier: "cell") else {
            return UITableViewCell()
        }

        let entity = fetchedResultsControler.object(at: indexPath)

        result.accessoryType = .disclosureIndicator
        result.textLabel?.text = entity.value(forKey: "name") as? String

        return result
    }

    override func tableView(_ tableView: UITableView, titleForHeaderInSection section: Int) -> String? {
        if let fetchedObjects = fetchedResultsControler.fetchedObjects {
            if section == 0 && fetchedObjects.count > 0 {
                return instructionsText
            }
        }
        return nil
    }

    // MARK: - UITableViewDelegate

    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        let selectedEntity = fetchedResultsControler.object(at: indexPath)

        parentObject.setValue(selectedEntity, forKey: parentRelationshipKeyPath)

        let mutableGuns = selectedEntity.mutableSetValue(forKey: propertyInverseRelationshipKeyPath)
        mutableGuns.add(parentObject)

        AppDelegate().saveContext()

        editPropertyControllerDelegate?.controllerDidFinish(self)
    }

    @objc func addButtonTapped(sender: UIBarButtonItem) {
        let childContext = NSManagedObjectContext(concurrencyType: .mainQueueConcurrencyType)
        childContext.parent = managedObjectContext

        let childEntity = NSEntityDescription.insertNewObject(forEntityName: propertyEntityName, into: childContext)

        let controller = DBStringEditController(managedObject: childEntity, forKey: "name")
        controller.delegate = self
        controller.navigationItem.title = addNewTitle
        controller.textField.placeholder = Strings.LABEL_NAME
        let navigationController = UINavigationController(rootViewController: controller)

        present(navigationController, animated: true, completion: nil)
    }

    @objc func cancelButtonTapped(sender: UIBarButtonItem) {
        editPropertyControllerDelegate?.contorllerDidCancel(self)
    }

    // MARK: - DZNEmptyDataSetSource
    func title(forEmptyDataSet scrollView: UIScrollView!) -> NSAttributedString! {
        let title = Strings.MESSAGE_NO_ITEMS_PRESENT
        let attributes = [NSAttributedString.Key.font: UIFont.preferredFont(forTextStyle: .headline)]
        return NSAttributedString(string: title, attributes: attributes)
    }

    func description(forEmptyDataSet scrollView: UIScrollView!) -> NSAttributedString! {
        let title = Strings.MESSAGE_NO_ITEMS_PRESENT
        let attributes = [NSAttributedString.Key.font: UIFont.preferredFont(forTextStyle: .body)]
        return NSAttributedString(string: title, attributes: attributes)
    }

    // MARK: - DZNEmptyDataSetDelegate
    func emptyDataSetShouldDisplay(_ scrollView: UIScrollView!) -> Bool {
        return true
    }

    // MARK: - NSFetchedResultsControllerDelegate
    func controllerWillChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
        tableView.beginUpdates()
    }

    func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>, didChange anObject: Any, at indexPath: IndexPath?, for type: NSFetchedResultsChangeType, newIndexPath: IndexPath?) {
        switch type {
        case .insert:
            tableView.insertRows(at: [newIndexPath!], with: .fade)
        case .delete:
            tableView.deleteRows(at: [indexPath!], with: .fade)
        case .update:
            tableView.reloadRows(at: [indexPath!], with: .fade)
        case .move:
            tableView.moveRow(at: indexPath!, to: newIndexPath!)
        @unknown default:
            fatalError()
        }
    }

    func controllerDidChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
        tableView.endUpdates()
    }

    // MARK: - DBEditPropertyControllerDelegate
    func controllerDidFinish(_ controller: UIViewController) {
        if let context: NSManagedObjectContext = (controller as! DBStringEditController).managedObjectContext, context.hasChanges {
            do {
                try context.save()
                dismiss(animated: true, completion: nil)
            } catch {
                let nserror = error as NSError
                validationHelper.showCoreDataValidationErrors(error: nserror, controller: controller)
            }
        }
    }

    func contorllerDidCancel(_ controller: UIViewController) {
        controller.dismiss(animated: true)
    }
}

Benefits

• I went from multiple copies of almost the same code to only one class.
• I deleted numerous unit tests that were no longer needed.
• I left the door open for further subclassing and customization while still maintaining a very tight codebase. In example - I could derive a separate controller that deals only with Gun attributes or one only with Ammo attributes.

class GunPropertyEditController<T: NSManagedObject>: DBEntityPropertyEditController<T> {

    convenience init(
        gun: Gun,
        entityName: String,
        navigationItemTitle: String,
        addNewTitle: String,
        instructionsText: String,
        gunRelationshipKeyPath: String
    ) {
        self.init(
            parentObject: gun,
            propertyEntityName: entityName,
            navigationItemTitle: navigationItemTitle,
            addNewTitle: addNewTitle,
            instructionsText: instructionsText,
            parentRelationshipKeyPath: gunRelationshipKeyPath,
            propertyInverseRelationshipKeyPath: "guns"
        )
    }
}

I could also go a step further and subclass one more time per attribute in case I wanted to do something different.

class GunTypeEditController: GunPropertyEditController<GunType> {
    convenience init(gun: Gun) {
        self.init(
            gun: gun,
            entityName: "GunType",
            navigationItemTitle: Strings.TITLE_SELECT_GUN_TYPE,
            addNewTitle: Strings.TITLE_NEW_GUN_TYPE,
            instructionsText: Strings.MESSAGE_EDIT_GUN_TYPE_INSTRUCTIONS,
            gunRelationshipKeyPath: "type"
        )
    }
}

Whatever the reason might be, this new base DBEntityPropertyEditController would handle all the boilerplate work, leaving the subclasses with the minimal task of providing their specific configurations.

Conclusion

Taking the time to refactor duplicated code is always a worthwhile investment. It pays dividends in reduced complexity, improved stability, and faster development down the road. So next time you find yourself reaching for copy-paste, take a moment to consider if a base class or another form of abstraction could save you from a future maintenance nightmare. Your future self will thank you.

The workflow looks as follows:

sequenceDiagram
        participant Client
        participant Auth
        participant Api
        activate Client
        Client->>Client: generate client_assertion
        Client->>Client: sign client_assertion with private key
        Client->>Auth: Exchange client assertion for access_token
        activate Auth        
        Auth->>Auth: Verify client_assertion with public key
        Auth->>Auth: Generate access_token
        Auth->>Auth: Sign access_token with private key
        Auth->>Client: return access_token
        deactivate Auth
        Client->>Api: Get protected resource with access_token
        activate Api
        Api->>Auth: Get public key from JWKS
        activate Auth
        Auth->>Api: return public key
        deactivate Auth
        Api->>Api: Verify access_token with public key
        Api->>Client: Return protected resource
        deactivate Api
        deactivate Client

The codebase includes:

1. Bootstrapper: Generates a public-private key pair and a JWKS.
2. Auth Server: Exposes routes to serve the JWKS and issue signed access tokens.
3. API Server: Protects a route, validating access tokens using the Auth server’s JWKS.
4. Client: Signs a client assertion and exchanges it for an access token from the Auth server to access the API’s protected resource.

Below are step-by-step instructions, complete with sample code, to set up and run this system.

• Step 1: Project Setup
• Step 2: Bootstrapper - Generating Keys and JWKS
• Step 3: Auth Server - Serving JWKS and Signing JWTs
• Step 4: API Server - Protecting a Route with JWT Validation
• Step 5: Client - Fetching Token and Accessing Protected Resource
• Step 6: Docker Compose Setup
• Step 7: Running the System
• Step 8: Testing Manually
• Conclusion

Prerequisites

• Node.js (v18 or higher)
• Docker and Docker Compose
• Basic understanding of JWTs, public-private key cryptography, and Node.js.

Step 1: Project Setup

Create a project directory with the following structure (files will be added in the steps below):

node-jwks-demo/
├── bootstrapper/
│   ├── index.js
│   └── package.json
├── auth/
│   ├── index.js
│   └── package.json
├── api/
│   ├── index.js
│   └── package.json
├── client/
│   ├── index.js
│   └── package.json
├── docker-compose.yml
└── keys/
    ├── private.pem
    ├── public.pem
    └── jwks.json

We’ll use Docker Compose to run all services. The keys/ directory will store the generated keys and JWKS.

Step 2: Bootstrapper - Generating Keys and JWKS

The Bootstrapper generates an RSA key pair and a JWKS file using the jose library.

Code for Bootstrapper

Create bootstrapper/package.json:

{
  "name": "bootstrapper",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "jose": "^6.0.12"
  },
  "scripts": {
    "start": "node index.js",
    "lint": "eslint ."
  },
  "type": "module",
  "devDependencies": {
    "@eslint/js": "^9.31.0",
    "eslint": "^9.31.0",
    "globals": "^16.3.0",
    "prettier": "3.6.2"
  }
}

Create bootstrapper/index.js:

import { writeFileSync } from "fs";
import { generateKeyPair, exportSPKI, exportPKCS8, exportJWK } from "jose";

// Define the path where keys will be saved
const path = "../keys/";

async function generateAndSaveKeys() {
  // Generate a key pair (RSA or EC — we'll use RSA here)
  const { publicKey, privateKey } = await generateKeyPair("RS256", {
    modulusLength: 2048, // recommended key size
    extractable: true,
  });

  // Export the public/private keys to PEM format
  const publicPem = await exportKeyToPEM(publicKey);
  const privatePem = await exportKeyToPEM(privateKey);

  // Export the public key to JWK format
  const jwk = await exportKeyToJWK(publicKey);

  // 4. Optionally add desired metadata
  jwk.use = "sig";
  jwk.alg = "RS256";
  jwk.kid = "client-key"; // optional, but recommended

  // Wrap in JWKS format
  const jwks = {
    keys: [jwk],
  };

  // Write keys to files
  writeFileSync(`${path}public_key.pem`, publicPem);
  writeFileSync(`${path}private_key.pem`, privatePem);
  writeFileSync(`${path}jwks.json`, JSON.stringify(jwks));

  console.log(
    `✅ Keys generated and saved to ${path} as public_key.pem and private_key.pem`
  );
}

async function exportKeyToPEM(key) {
  const pem = await exportSPKI(key).catch(() => exportPKCS8(key));
  return pem;
}

async function exportKeyToJWK(key) {
  const jwk = await exportJWK(key);
  return jwk;
}

generateAndSaveKeys().catch(console.error);

Explanation

• The jose library generates an RSA key pair with the RS256 algorithm.
• The public and private keys are exported in PEM format and saved to keys/.
• The public key is converted to a JWK and wrapped in a JWKS object with a kid (key ID) for identification.

Step 3: Auth Server - Serving JWKS and Signing JWTs

The Auth server provides two endpoints:

• /jwks.json: Returns the JWKS.
• /token: Signs and returns a JWT.

Code for Auth Server

Create auth/package.json:

{
  "name": "auth",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "body-parser": "^2.2.0",
    "express": "^5.1.0",
    "jose": "^6.0.12"
  },
  "scripts": {
    "start": "node index.js"
  },
  "type": "module",
  "devDependencies": {
    "@eslint/js": "^9.31.0",
    "eslint": "^9.31.0",
    "globals": "^16.3.0"
  }
}

Create auth/index.js:

import jwksjson from "../keys/jwks.json" with { type: "json" };
import express from "express";
import * as jose from "jose";
import fs from "fs";
import bodyParser from "body-parser";

const app = express();
const port = 3001;

// create application/x-www-form-urlencoded parser
const urlencodedParser = bodyParser.urlencoded();

const pathToPrivateKeyFile = new URL("../keys/private_key.pem", import.meta.url)
  .pathname;
const privateKeyFile = fs.readFileSync(pathToPrivateKeyFile, "utf8");

const privateKey = await jose.importPKCS8(privateKeyFile, "RS256");

const pathToPublicKeyFile = new URL("../keys/public_key.pem", import.meta.url)
  .pathname;

const publicKeyFile = fs.readFileSync(pathToPublicKeyFile, "utf8");

const publicKey = await jose.importSPKI(publicKeyFile, "RS256");

app.post("/token", urlencodedParser, async (req, res) => {
  console.info("Received request to /token endpoint");

  console.info("Validating request body...");

  // Check to see if the request body is present
  if (!req.body) {
    console.error("Request body is missing");
    return res.status(400).json({ error: "Request body is required" });
  }

  // Check to see if the client_id is present in the request body
  if (!req.body.client_id && req.body.client_id !== "client") {
    // ADD additional check for valid client_id here if needed
    console.error("Missing or invalid client_id in request body");
    return res.status(400).json({ error: "Missing or invalid client_id" });
  }

  // Check to see if the client_assertion_type is present in the request body
  if (
    !req.body.client_assertion_type &&
    req.body.client_assertion_type !==
      "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
  ) {
    console.error("Missing or invalid client_assertion_type in request body");
    return res
      .status(400)
      .json({ error: "Missing or invalid client_assertion_type" });
  }

  // Check to see if the client_assertion is present in the request body
  if (!req.body.client_assertion) {
    console.error("Missing client_assertion in request body");
    return res.status(400).json({ error: "Missing client_assertion" });
  }

  console.info("Request body validation successful");

  const client_assertion = req.body.client_assertion;

  console.log("client_assertion:", client_assertion);

  // Verify the client_assertion
  console.info("Verifying client_assertion...");
  try {
    const payload = await jose.jwtVerify(client_assertion, publicKey, {
      issuer: "client",
      audience: "auth",
    });

    console.info("client_assertion successfully verified");
    console.log("Verified client_assertion payload:", payload);

    console.info("Generating access token...");
    const access_token = await new jose.SignJWT({
      sub: payload.sub,
      user: "exampleUser",
    })
      .setProtectedHeader({ alg: "RS256", kid: "client-key" })
      .setIssuedAt()
      .setIssuer("auth")
      .setAudience("api")
      .setExpirationTime("2h")
      .sign(privateKey);

    console.info("Access token generated successfully");
    console.info("Returning access token to client...");
    res.json({ token: access_token });
  } catch (err) {
    console.error("Invalid client_assertion:", err.message);
    res.status(401).json({ error: "Invalid client_assertion" });
  }
});

/**
 * Endpoint to serve the JWKS (JSON Web Key Set) for public key retrieval.
 * This is typically used for verifying JWTs (JSON Web Tokens).
 */
app.get("/.well-known/jwks.json", (req, res) => {
  res.setHeader("Content-Type", "application/json");
  res.send(jwksjson);
});

app.get("/health", (req, res) => {
  res.status(200).json({ status: "ok" });
});

app.listen(port, () => console.log(`Auth server running on port ${port}`));

Explanation

• The /.well-known/jwks.json endpoint serves the JWKS file generated by the Bootstrapper.
• The /token endpoint verifies a client assertion and then signs and returns an access token with the private key, including a subject (sub), scope, and expiration.
• The kid in the JWT header matches the JWKS for validation.

Step 4: API Server - Protecting a Route with JWT Validation

The API server validates incoming JWTs using the Auth server’s JWKS.

Code for API Server

Create api/package.json

{
  "name": "api",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "express": "^5.1.0",
    "jose": "^6.0.12"
  },
  "scripts": {
    "start": "node index.js"
  },
  "type": "module",
  "devDependencies": {
    "@eslint/js": "^9.31.0",
    "eslint": "^9.31.0",
    "globals": "^16.3.0"
  }
}

Create api/index.js:

import express from "express";
import * as jose from "jose";

const app = express();
const port = 3002;
const JWKS_URL = "http://auth:3001/.well-known/jwks.json";

console.info("Retrieving JWKS...");
const clientJWKSet = jose.createRemoteJWKSet(new URL(JWKS_URL));
console.info("JWKS successfully retrieved");

app.get("/protected", async (req, res) => {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res
      .status(401)
      .json({ error: "Missing or invalid Authorization header" });
  }

  const token = authHeader.split(" ")[1];
  try {
    const { payload } = await jose.jwtVerify(token, clientJWKSet, {
      algorithms: ["RS256"],
    });
    res.json({ message: "Protected resource accessed", user: payload.sub });
  } catch (error) {
    console.error("JWT verification error:", error);
    res.status(401).json({ error: "Invalid or expired token" });
  }
});

app.listen(port, () => console.log(`API server running on port ${port}`));

Explanation

• The /protected endpoint checks for a Bearer token in the Authorization header.
• The jose library’s createRemoteJWKSet fetches the JWKS from the Auth server to validate the token.
• If valid, the endpoint returns a success message with the token’s subject.

Step 5: Client - Fetching Token and Accessing Protected Resource

The Client exchanges a signed client assertion for an access token from the Auth server and uses it to access the API’s protected route.

Code for Client

Create client/package.json:

{
  "name": "client",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "axios": "^1.6.7"
  },
  "scripts": {
    "start": "node index.js"
  }
}

Create client/index.js:

import axios from "axios";
import * as jose from "jose";
import fs from "fs";

async function runClient() {
  console.info("Generating client assertion...");

  const pathToPrivateKeyFile = new URL(
    "../keys/private_key.pem",
    import.meta.url
  ).pathname;
  const privateKeyFile = fs.readFileSync(pathToPrivateKeyFile, "utf8");

  const privateKey = await jose.importPKCS8(privateKeyFile, "RS256");

  const now = Math.floor(Date.now() / 1000);

  const clientAssertion = await new jose.SignJWT({ sub: "client" })
    .setProtectedHeader({ alg: "RS256" })
    .setIssuedAt(now)
    .setIssuer("client")
    .setAudience("auth")
    .setExpirationTime("5m")
    .sign(privateKey);

  console.info("Client Assertion generated successfully");
  console.log("Client Assertion:", clientAssertion);

  try {
    console.info(
      "Exchanging client assertion for access_token from Auth server..."
    );

    const tokenResponse = await axios.post(
      "http://auth:3001/token",
      {
        client_assertion: clientAssertion,
        client_assertion_type:
          "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
        client_id: "client",
      },
      {
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
      }
    );

    const token = tokenResponse.data.token;

    console.info("Access_token received successfully:");
    console.log("Token:", token);

    console.info("Accessing protected API...");

    const apiResponse = await axios.get("http://api:3002/protected", {
      headers: { Authorization: `Bearer ${token}` },
    });

    console.info("Protected API accessed successfully");

    console.log("API Response received:", apiResponse.data);
  } catch (error) {
    console.error(
      "Client error:",
      error.response ? error.response.data : error.message
    );
  }
}

runClient();

Explanation

• The Client uses jose to sign a client assertion.
• The Client uses axios to exchange the client assertion for an access token from the Auth server’s /token endpoint.
• It then sends the access token in the Authorization header to the API’s /protected endpoint.

Step 6: Docker Compose Setup

Create docker-compose.yml in the root directory to orchestrate the services:

services:
  bootstrapper:
    build: ./bootstrapper
    volumes:
      - ./keys:/keys
    command: npm start
    profiles:
      - bootstrap
  auth:
    build: ./auth
    ports:
      - "3001:3001"
    volumes:
      - ./keys:/keys
    command: npm start
    profiles:
      - stack
  api:
    build: ./api
    ports:
      - "3002:3002"
    volumes:
      - ./keys:/keys
    depends_on:
      - auth
    command: npm start
    profiles:
      - stack
  client:
    build: ./client
    depends_on:
      - api
    volumes:
      - ./keys:/keys
    command: npm start
    profiles:
      - stack

Explanation

• Each service is built from its respective directory.
• The keys/ directory is shared as a volume to persist keys and JWKS.
• The bootstrap and stack profiles are used to organize the components.

Step 7: Running the System

• Ensure Docker is running.
• In the jwt-demo/ directory, run the following command to generate the keys:

docker-compose --profile bootstrap up --build --force-recreate

• In the jwt-demo/ directory, run the following command to spin up the stack:

docker-compose --profile stack up --build --force-recreate

Expected Output

• The Bootstrapper logs: Keys and JWKS generated successfully.
• The Auth server logs: Auth server running on port 3001
• The API server logs: API server running on port 3002
• The Client logs: API Response: { message: 'Protected resource accessed' }

Step 8: Testing Manually

You can test the system using curl or a tool like Postman:

Get the JWKS:

curl http://localhost:3001/jwks.json

Get a token:

curl http://localhost:3001/token

Access the protected resource:

curl -H "Authorization: Bearer <token>" http://localhost:3002/protected

Conclusion

This system demonstrates how to use public-private key pairs, JWKS and client assertion for secure JWT handling in a Node.js environment. The jose library simplifies key management and JWT operations, while Docker Compose ensures easy setup. You can extend this by adding more robust error handling, token refresh mechanisms, or additional protected routes.

For the full codebase, check out the GitHub repository.

and full screen when in landscape mode.

I thought this would be a simple task until I ended up spending over 2 hrs trying to fine-tune it so I figured I’d write about it.

• Set Up
• Primary image
• Rotation support

Set up

We’ll keep it very simple - 1 grouped-style table with 3 sections and 5 rows inside each section.

import UIKit
class ViewController: UITableViewController {

    convenience init() {

        self.init(style: UITableViewStyle.grouped)

    }

    override func viewDidLoad() {
        super.viewDidLoad()
        self.navigationItem.title = "Gun details"

    }


    // ***********************************************
    // MARK: - UITableViewDataSource
    // ***********************************************



    override func numberOfSections(in tableView: UITableView) -> Int {

        return 3

    }


    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {

        return 5

    }


    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {

        // since it is a static view we don't care about recycling at this time
        let result: UITableViewCell = UITableViewCell(style: .value1, reuseIdentifier: "cell")

        result.textLabel?.text = "Text for row at: \(indexPath.row)"
        result.detailTextLabel?.text = "Details for row at: \(indexPath.row)"

        return result

    }

}

Primary image

In order to add a primary image on top we need to override 2 methods: heightForHeaderInSection and viewForHeaderInSection. The first one controlls the height of placeholder we are going to use for the image and the second one provides the actual image to be displayed.

Note that we are not using the device orientation but the statusBar orientation instead. This is because while the device can be rotated - the interface could be locked for rotation in the same time.

override func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat {

    if section == 0 {
        let orientation = UIApplication.shared.statusBarOrientation

        if orientation.isLandscape {
            return view.frame.height
        } else {
            return view.frame.height / 3
        }
    }

    return UITableViewAutomaticDimension

}

override func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {

    // We'll assume that there is only one section for now.

    if section == 0 {

        let imageView: UIImageView = UIImageView()
        imageView.clipsToBounds = true
        imageView.contentMode = .scaleAspectFill
        imageView.image =  UIImage(named: "gun")!
        return imageView
    }

    return nil

}

Rotation support

The last thing that is left to add it the rotation support. Note that there are 3 phases that allow hooks. For our purpose we’ll use the before rotation and during rotation to invalidate the table layout. My first try was actually adding tableView.reloadData() instead but it resulted in a flicker of the screen so beginUpdates() and endUpdates() ended up being the better choice.

override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
    super.viewWillTransition(to: size, with: coordinator)

    //        print("will execute before rotation")

    self.tableView.beginUpdates()

    coordinator.animate(alongsideTransition: { (context: UIViewControllerTransitionCoordinatorContext) in

        //            print("will execute during rotation")

        self.tableView.endUpdates()

    }) { (context: UIViewControllerTransitionCoordinatorContext) in

        //            print("will execute after rotation")

    }

}

That’s it. Now you have a nice table view with a smart primary image.

For the full codebase, check out the GitHub repository.