Appendix H: Claudes LockBox (Shop Manual)

Status: v1.0 submitted to App Store APR 16 2026, awaiting review. GPL v3. Public repo at github.com/fluhartyml/Claudes-LockBox. Build-Along chapter: Part VII Build-Along 03. Claudes LockBox is a biometric vault for personal documents and photos: Face ID at launch, folders inside, items inside folders, attached camera shots or scanned PDFs at the item level. It's the Bible's primary Live Reference for gestures (Book 04), three-column navigation (Book 13), sheet vs. fullScreenCover (Book 12), and share-sheet integration (Book 14).

What it is

A SwiftUI iPhone / iPad / Mac (Designed for iPad on Mac) app that gates everything behind Face ID. After successful authentication, the user sees a sidebar of folders, the items inside the selected folder, and the per-item detail screen. Items hold photos taken with the camera, document pages scanned with VisionKit's document scanner, free-form text notes, and PIN-protected secure entries. The data lives in SwiftData, hosted in the app's sandbox — nothing leaves the device.

Architecture overview

Standard SwiftUI + SwiftData app with a Face-ID-gated entry view. Three-column NavigationSplitView after auth. Camera and document-scanner integrations are UIViewController-based, bridged into SwiftUI via UIViewControllerRepresentable.

File roles:

• App entry: Claudes_LockBoxApp.swift (the @main scene with the SwiftData model container), LockScreenView.swift (Face ID gate, falls through to ContentView on success), ContentView.swift (root after auth — hosts the TabView with Vault and Under-the-Hood tabs).
• Three-column shell: SidebarView.swift (folders list, the leftmost column), ItemListView.swift (items inside the selected folder, the middle column), ItemDetailView.swift (the rightmost column).
• Add sheets: AddFolderView.swift (new folder form), AddItemView.swift (new item form — presented via fullScreenCover rather than .sheet; the rationale is in the gotchas section below).
• Photo capture and viewing:
  • CameraCaptureView.swift — UIKit camera bridge.
  • DocumentScannerView.swift — VisionKit document scanner bridge.
  • ImageViewerView.swift — full-screen image viewer with five gesture patterns (covered in Book 04).
  • ShareSheetView.swift — UIActivityViewController wrapped via UIViewControllerRepresentable.
• Data model: Folder.swift and VaultItem.swift — SwiftData @Model classes with relationships.
• Auxiliary surfaces: AboutView.swift, FeedbackView.swift.
• Under-the-Hood tab:
  • UnderTheHoodView.swift + UnderTheHoodContent.swift — the in-app source-mirror feature that lets the user browse the app's own SwiftUI views.
  • IdentifierTaggedSourceView.swift — renders source with tappable Swift identifiers.
  • LexiconSheet.swift + LexiconContent.swift — the popup that appears when a tapped identifier resolves to a Lexicon entry.

The Face ID gate

LockScreenView is the app's first surface after launch. It calls LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, ...) with a localized reason string; success replaces the gate with ContentView. Failure shows the gate again with a retry affordance. There's a PIN fallback for devices without Face ID or when biometrics is unavailable.

The lock screen is part of the SwiftUI view tree (not a presentation modal). On app backgrounding the gate re-asserts via scene phase changes — switching to another app and back re-prompts.

Data model

Two SwiftData entities and the relationships between them:

• Folder — id, name, createdDate, plus a relationship to its VaultItems with a cascade delete rule.
• VaultItem — id, title, body, createdDate, plus image / page / PIN payload fields. The item belongs to one folder via the inverse relationship.

The ModelContainer is wired in Claudes_LockBoxApp.swift. The .modelContainer(for: [Folder.self, VaultItem.self]) call seeds the SwiftData stack; the views read via @Query and write via @Environment(\.modelContext) with explicit insert/delete.

Gestures (Image Viewer)

ImageViewerView.swift hosts five gesture patterns in a single view, which is why Book 04 reaches for it as the chapter's worked example:

1. Tap a thumbnail → image opens full-screen.
2. Pinch → zoom in / out.
3. Double-tap → toggle between fit-to-screen and 3x zoom.
4. Drag (when zoomed in) → pan the image.
5. Pinch below 1x → snap back to fit-to-screen.

Long-press on a thumbnail in the detail view presents a context menu with "View Full Size" and "Delete Page" options.

Sheets, alerts, share

• Add Item form — fullScreenCover, not .sheet. See gotchas below for why.
• Image Viewer — .sheet. The pinch / zoom interaction is happier inside a sheet's resizable surface.
• Photo context menus — SwiftUI contextual-menu pattern.
• Delete operations — confirmation dialogs.
• About sheet — .sheet from the sidebar's info button.
• Share sheet — ShareSheetView wraps UIActivityViewController via UIViewControllerRepresentable.

Build + deployment

• App name: Claudes LockBox.
• Platforms: iPhone, iPad, Mac (via Designed for iPad).
• Frameworks: SwiftData (persistence), LocalAuthentication (Face ID), VisionKit (document scanner), AVFoundation (camera), UIKit (the wrapped UIViewControllers).
• Privacy: No network. All data stays in the device sandbox. NSCameraUsageDescription for the camera; NSFaceIDUsageDescription for biometrics.
• Submission: v1.0 submitted to App Store APR 16 2026. Awaiting review as of this manual's date.

Known gotchas

• Add Item is fullScreenCover, not .sheet. A .sheet at the iPhone partial-height presentation fights the keyboard — when the title field gains focus, the sheet's animated height adjustment clips the form. fullScreenCover takes the whole screen and the keyboard pushes content normally. Captured in Build-Along 03 §10 as one of three polish fixes from a single build-day commit.
• VisionKit document scanner needs camera permission. First scan triggers the camera permission prompt even though VisionKit is the surface; the underlying camera capture session is what the system asks about.
• Image viewer overpinch snap-back is part of the chapter teaching. The "pinch below 1x snaps to fit-to-screen" behavior is a small UX-payoff detail Book 04 walks through — it's not a default, it's a few lines in onChange(of: zoomScale) that re-anchor the image.
• Designed for iPad on Mac vs native macOS. LockBox runs on Mac via Designed-for-iPad-on-Apple-Silicon. A native macOS port would need LAContext Touch-ID-or-password fallback handling tuned for Mac biometrics, plus AppKit-flavored camera permissions. Not on the v1 roadmap.

Sources

• Project source: github.com/fluhartyml/Claudes-LockBox (verified 2026-05-10).
• Build-Along chapter: Part VII Build-Along 03, with §10 covering the fullScreenCover vs .sheet polish-day commit.
• Book 04 cross-reference: gestures (ImageViewerView.swift five-pattern walkthrough).
• Book 12 cross-reference: sheets, alerts, and confirmations.
• Book 13 cross-reference: three-column NavigationSplitView.
• Book 14 cross-reference: share sheet via wrapped UIKit controller.
• Book 19 cross-reference: LexiconSheet + IdentifierTaggedSourceView as custom-view examples.