Stanford CS193p： iOS Development with SwiftUI｜ L14： SwiftData Demonstration — Annotated Lecture Notes & Key Takeaways

Course Information

Institution: Stanford

Original Course: Stanford CS193p: iOS Development with SwiftUI | 2025 | L14: SwiftData Demonstration

Instructor Bio: This lecture is delivered by Paul Hegarty, Lecturer in Computer Science at Stanford University and the principal instructor of CS 193P since 2010. Paul Hegarty is a veteran software engineer and educator with deep roots in the Apple developer ecosystem. Earlier in his career he worked at NeXT Computer, where he contributed to the Objective-C language and the foundational tools that would eventually become Apple's modern development platform. He has taught iOS application development at Stanford for over fifteen years, guiding thousands of students through the transition from earlier UIKit frameworks to the modern SwiftUI declarative paradigm. He is widely recognized for his methodical teaching style, his emphasis on clean architectural patterns such as MVVM, and his ability to explain complex systems concepts through hands-on, live-coding demonstrations.

Course Description: This lecture is a hands-on demonstration integrating SwiftData persistence into the CodeBreaker application. It shows how to model game history records, save completed games to persistent storage, and query and display past games with complex sorting options and advanced predicates that traverse multiple database relationships. The session also covers migration considerations, undo/redo support, and best practices for keeping the persistence layer cleanly separated from the UI and business logic layers.

This lecture is entirely hands‑on demo work for SwiftData, walking through converting an existing Code‑Breaker iOS app to use the SwiftData persistence framework. Every major change the instructor makes is tied back to earlier work from lecture 13. The core keyword SwiftData appears throughout the code refactoring, debugging, and feature building work shown in the session. I will walk through what got changed, where bugs popped up, tricky implementation bits, and the new sorting and searching features built toward the end of the video.
 

Migrating existing model code to @Model

The starting point picks up right after lecture 13, where the instructor converted app models to use the @Model macro. He walks through each modified source file using git diff blue change markers to recap every adjustment, because code got rearranged across many files in the prior class session.

The Code type changed from a struct to a class decorated with @Model. Since SwiftData only works with primitive stored types, enum values could not be saved directly to the database. The enum property kind got switched over to store raw string values. A computed property handled back‑and‑forth conversion between the string storage and the original enum, and the conversion helper code was generated with ChatGPT.

Because it became a class, a custom initializer had to be written for Code. Structs get automatic member‑wise initializers, but classes do not. Methods like randomize and reset also lost their mutating keyword. Mutating only applies for struct value types; class methods modify instance state without needing that marker.

Color types could not live inside the model layer anymore. SwiftUI Color is UI‑framework specific, and the goal was to fully decouple the model from UI code. All peg color storage shifted to hexadecimal string representations. A missing peg placeholder value also switched away from a Color type.

Over in the CodeBreaker model class, imports shifted from SwiftUI to Foundation, fully severing UI dependencies in the model module. The peg values now stored strings instead of colors. Since CodeBreaker was already an @Observable class, adopting @Model did not require huge structural rewrites.

Relationship annotations had to be added for the collection of Code objects inside each game instance. The relationship setup meant deleting a CodeBreaker game record would cascade‑delete all its associated Code entries in the separate database table.

One tricky bug came from marking the startTime property @Transient. Properties tagged transient do not persist to disk. But @Transient variables also do not trigger SwiftUI view updates when their value changes. The elapsed game timer stopped refreshing the user interface. The instructor’s quick workaround was nudging another stored model variable (elapsedTime) by a tiny floating‑point increment every time startTime was assigned. Touching a persisted model property forced SwiftUI to recognize state change and redraw views. This is a hack, not an official framework feature (3:27).

The initializer for CodeBreaker dropped default color‑based peg choices, since colors no longer belong in the model. When creating guess copies for game attempts, explicit new Code instances needed manual creation because classes use reference semantics instead of struct value semantics. Auto‑generated protocol conformances like Identifiable, Hashable, Equatable are supplied automatically for @Model classes, so hand‑written extensions for those could be deleted.

On the view side, convenience computed properties and custom initializers were added as lightweight wrappers. These let view code keep working with Color values while internally translating back and forth to hex strings that the model stores. The instructor calls this lightweight MVVM. Instead of building full‑blown separate view‑model objects, UI‑specific conversion logic lives in view‑layer extensions. This keeps most existing view logic from needing massive rewrites.

Several supporting UI components required small tweaks. The game editor’s peg picker UI works with SwiftUI Color, so it binds to those convenience conversion wrappers. The peg display view takes hex strings from the model and converts them back into Color for drawing shapes on‑screen. Preview providers had minor adjustments feeding hex‑string sample data.
 

Setting up ModelContainer and fixing Xcode Previews for SwiftData

With model classes converted, the next step was adding a ModelContainer in the app entry point. The container sets up the underlying SQL storage and maps @Model Swift classes to database tables.

A big headache emerges for Xcode previews. Previews run in isolated contexts and do not execute the main app entry‑point setup code. Without an active ModelContainer, preview canvases crash immediately when instantiating any @Model object (9:37).

You cannot simply attach .modelContainer() as a view modifier directly inside the preview block. The preview provider itself is not a SwiftUI view, so view modifiers cannot attach to it. The instructor’s advanced solution builds a custom PreviewModifier. This is a special preview‑only construct distinct from ordinary view modifiers.

He creates a new file dedicated to this preview helper. The custom preview modifier uses an asynchronous, throwing static function makeSharedContext to spin up a fresh ModelContainer. Critically, the configuration sets isStoredInMemoryOnly: true. Preview data lives only in memory and never writes anything to disk. That avoids leftover preview junk accumulating in your local app database. A static extension on PreviewTrait creates a clean dot‑syntax calling style, so every preview can opt‑in with .previewTraits(.swiftData). The @MainActor annotation gets added to keep preview database work on the main UI thread.

The instructor notes this is fairly advanced Swift. For people who do not want to parse every line, you can copy‑paste this helper file and only swap out your own @Model type name. Every view preview that touches SwiftData objects needs this trait attached, otherwise it will crash. Independent small sub‑views that take plain data values and do not instantiate model objects do not need the preview trait.
 

Replacing in‑memory state with @Query and ModelContext

Up to this point, the app held its list of games inside an @State array variable in a view. That array was the source of truth. Now the database becomes source of truth. The @State array gets replaced with an @Query property.

@Query fetches model objects from the database. It automatically stays live: when underlying database records get inserted, deleted, or edited, the array returned by @Query updates automatically, refreshing SwiftUI views. The result collection is read‑only. You cannot append or remove items directly on the query array. All mutations must go through ModelContext.
ModelContext is your handle for interacting with the database. You pull it from the environment using @Environment(\.modelContext). Important operations available are insert(), delete(), fetch(), fetchCount(), and save(). Auto‑save normally happens when the application moves to the background. When actively developing in Xcode and hitting stop on the debugger, the app does not properly background, so auto‑save never fires. Changes can get lost if you kill the running simulator that way (33:06).

All old array‑manipulating code had to be rewritten. Swipe‑to‑delete loops use modelContext.delete(game) instead of removing array indices. Editing an existing game works by deleting the old instance and inserting the edited copy. Creating new games just calls insert. The old .onMove list reorder modifier got removed. Since the @Query had explicit sorting by game name, manual row reordering no longer makes sense. If you wanted manual drag‑reorder support, you would need to add a custom ordering field on your model.

One subtle timing trap: calling insert adds objects to the context, but the @Query array does not refresh instantly. Updates happen on the next SwiftUI view update cycle. Right after inserting sample game data, trying to immediately index into the games array can crash because the collection still appears empty.

The instructor also demonstrates manual fetching using FetchDescriptor. @Query is the preferred high‑level tool, but sometimes you want direct manual fetches from modelContext. Fetch operations can throw errors so you need do‑catch blocks, try!, or try?. fetchCount() is more efficient than fetching full objects when you only need a total record count, as it runs purely as a SQL count operation without instantiating Swift model objects.

A major bug popped up related to model relationships. Each CodeBreaker game holds an array of related Code attempt objects stored in a separate database table. When loaded back from disk, relationship collections return in random order. That completely breaks Code‑Breaker gameplay, because the sequence of user guesses matters.

The fix adds a timestamp stored property on the Code model, recording creation date whenever a guess attempt is created. The underlying relationship property gets renamed to an underscore‑prefixed private storage variable. A public computed property wraps access: its getter always sorts the underlying collection by timestamp to guarantee chronological order. The setter assigns directly to private storage. UI code interacts exclusively with the sorted computed property and does not touch the raw unsorted storage.

Changing model properties (adding the timestamp field) alters the database schema. Running against existing stored data will cause loading failures. In production shipping apps you need schema migration logic built into SwiftData. During development, deleting the simulator app wipes the local database and resets everything.
 

Adding user‑controlled sort order and text search

With persistence working, the lecture moves on to building dynamic sorting and search features that leverage database query capabilities.

An enum conforming to CaseIterable defines available sort options: sort by name, or sort by most recent attempt. A segmented Picker UI control sits at the top of the game list view for switching sort modes.

One key limitation the instructor emphasizes: @Query properties can only configure their filter and sort parameters inside their containing view’s init(). You cannot mutate sorting criteria mid‑execution inside view body code. The solution is to push the sort‑selection value down as an input argument into the game‑list view. Inside the view initializer, switch on the passed‑in sort option and construct the appropriate Query instance.

To sort by recency, add a lastAttemptDate optional date property to CodeBreaker. Every time a user submits a guess attempt, update this property to the current date. For newly created games with zero attempts, this value starts as nil. Nil values sort unpredictably; the instructor notes you could default it to the game creation timestamp instead.

When switching sort modes, list rows re‑order instantly without animation. You can wrap the binding value in an animation to animate the list rearrangement.

Next is adding search functionality. SwiftUI’s built‑in .searchable() view modifier supplies a standard system search bar. The search text value flows down as another input argument to the game‑list view. Inside the initializer, a predicate filters the query results.

Predicate closures for SwiftData have restrictions. Not every Swift method works inside predicate logic. For example, you cannot directly call .lowercased() string methods inside the predicate closure. To implement case‑insensitive searching, pre‑compute lower‑case and capital‑cased versions of your search string outside the predicate closure and reference those constants inside the predicate.

The lecture closes by outlining assignment five requirements. Students take their prior assignment‑four Code‑Breaker implementation, migrate models over to @Model, add persistence, and implement sorting plus searching features. Most of the heavy work is converting models to SwiftData. Once that is complete, inserting, deleting, and querying data becomes fairly straightforward.
 

Unanswered / tricky points raised in the lecture

The instructor brings up multiple loose ends. The @Transient hack for fixing elapsed‑time UI updates is a workaround, not official framework design. There is no clean built‑in way to make transient properties trigger observation updates.

Schema migration for production applications gets mentioned but receives zero demo code. Students in class are told to just delete the simulator app during development, but real‑world apps must handle migrating user’s existing saved data when model types change. No concrete example is shown.

Also, the auto‑save trigger only fires on app backgrounding. Debug‑session simulator termination loses unsaved changes, and there is no demo showing strategic manual save() calls to mitigate that issue for development or edge‑case production scenarios.