Architecture
SwiftUI, iOS 26.5+, no third-party dependencies.
Lives at ios/truelable, scheme truelable. Native SwiftUI, no
external Swift packages — networking, persistence, and design system are
all hand-built against Apple's own frameworks (URLSession, SwiftData,
Keychain Services).
Layout
truelable/
├── App/
│ ├── TrueLabelApp.swift Entry point — owns the ModelContainer, the AppRouter environment object
│ └── RootView.swift TabView (Home/History/Verify/You) + bottom-accessory Scan button
├── Core/
│ ├── APIClient.swift All networking — see /docs/ios/networking
│ ├── APIEnvironment.swift Base URL (API_BASE_URL env override)
│ ├── DeviceAuth.swift Keychain-backed bearer token, single-flight registration
│ ├── Account.swift Sign in with Apple / name-only identity
│ ├── Capabilities.swift Feature flags (signInWithApple, off by default)
│ ├── Preferences.swift DietaryPreference, PersonalCheck, Threshold — see below
│ ├── Plus.swift Subscription state (backend- or StoreKit-sourced)
│ ├── Product.swift Product/Nutrition models, tolerant decoding
│ ├── ScanRecord.swift @Model — the one SwiftData persistence type
│ ├── NutritionParser.swift OCR text → Nutrition
│ ├── BarcodeChecksum.swift EAN/UPC mod-10 validation
│ └── CrashReporter.swift MetricKit subscriber — see below
├── Design/
│ ├── Theme.swift enum TL — every design token (see below)
│ └── Components.swift Buttons, ScoreRing, GradeStrip, BarMeter, StatTile, ProductCardRow, ...
├── Features/
│ ├── Home/ Landing tab — search bar, stat tiles, recents/popular strips
│ ├── Onboarding/ 3-page welcome/trust-model/dietary-preferences flow
│ ├── Scan/ Camera + reticle + manual-entry sheet
│ ├── Product/ Result screen and its cards (verdict, macros, sugar, allergens, alternatives, ...)
│ ├── History/ Searchable scan history + compare mode
│ ├── Verify/ Swipeable confirmation queue
│ ├── Profile/ "You" tab — account, impact stats, trends, Plus, dietary chips
│ ├── Account/ Sign in with Apple / name-only variants, delete account
│ ├── Plus/ Marketing screen + subscription gate
│ ├── Contribute/ Live-capture OCR wizard
│ └── Search/ Debounced search sheet
├── TrueLabel.storekit Local StoreKit config for testing Plus (monthly/yearly)
├── truelable.entitlements
└── PrivacyInfo.xcprivacy Required Reason API declarations (UserDefaults — CA92.1)Navigation — AppRouter
An @Observable environment object (App/TrueLabelApp.swift):
enum Tab { case home, history, verify, you }
enum Sheet: Identifiable { case manualEntry, search }
var tab: Tab = .home
var scannerPresented = false
var sheet: Sheet?RootView wires .fullScreenCover(isPresented: $router.scannerPresented)
to ScanScreen(), and .sheet(item: $router.sheet) to ManualEntrySheet
/ SearchSheet. Scanning lives in the tab bar's
.tabViewBottomAccessory, not a fifth tab — reachable from anywhere
without leaving the current tab. Each top-level tab owns its own
NavigationStack and pushes a barcode string via
.navigationDestination(for: String.self) into ProductLoaderScreen.
Screen-local sheets (the compare picker on the product screen, the camera
cover in the contribute flow) stay local to that screen rather than
routing through AppRouter.
Persistence — ScanRecord
The one SwiftData model (Core/ScanRecord.swift):
@Model
final class ScanRecord {
@Attribute(.unique) var barcode: String
var name, brand: String
var imageURL: String?
var scannedAt: Date
var scanCount: Int
var calories: Int?
var sugarGrams, sodiumMg, proteinGrams: Double?
var nutriscoreGrade: String?
var novaGroup: Int?
var verified: Bool
var snapshot: Data // full Product JSON — decoded lazily via `.product`
}ScanRecord.record(_:in:bump:) is the one insert-or-update entry point
(called from ProductLoaderScreen.load()), upserting by barcode. The
store lives in its own file (truelabel-v2.store, Application Support)
with self-healing — if it fails to open (a schema mismatch from an older
install), it's deleted and recreated rather than crashing the app.
Everything else is @AppStorage/UserDefaults, not SwiftData: dietary
preferences, the onboarding flag, verified-count tracking, cached account
identity, recent searches.
Dietary preferences
Core/Preferences.swift — 10 cases: vegetarian, vegan, lowSugar,
lowSodium, highProtein, peanutAllergy, lactoseSensitive,
glutenFree, noPalmOil, jain. Stored as a comma-joined string in
@AppStorage, evaluated against a scanned Product by
PersonalCheck.run(_:on:), which returns .good / .caution / .avoid /
.unknown with a real message — preferring structured tags
(labels/allergens/traces/nutrientLevels) and falling back to
ingredient-text keyword matching only for community-sourced products with
no tags.
Local-first, server-synced
RootView.task pulls dietary_preferences from
GET /api/v1/me/profile on launch only if local storage is empty —
a fresh install after a reinstall, never an overwrite of what's already
set locally. .onChange(of: dietaryRaw) pushes local changes back via
PUT /api/v1/me/profile. Preferences are local-first with best-effort
backend sync, not purely local and not purely server-owned.
There's no separate "health profile" screen — the equivalent UI is the
product screen's ForYouCard plus the shared DietaryChips component
(used on both Onboarding's third page and the Profile tab's "Watch for"
card).
Design tokens — Design/Theme.swift
enum TL, dark-only. Warm charcoal ground (bg #0C0B0A), a bone-colored
brand accent (#EFE6D4) deliberately kept off the verdict color ramp —
so the brand color never also means "this product is good," which would
quietly bias the UI. A full Nutri-Score-letter verdict ramp (good→danger),
two chart-only hues, and brass reserved for Plus only. One motion curve
(Animation.tl(_:), the same ease-out-expo as the web app). Display type
is serif (New York) — the one typographic signature; body/UI stay SF.
.card(_:fill:) is the one surface treatment app-wide, using real
.glassEffect() with a reduceTransparency accessibility fallback to a
flat fill. .screenBackground() is a flat fill plus a static
MeshGradient — explicitly not animated, so it costs nothing at runtime.
Crash reporting
Core/CrashReporter.swift, installed from TrueLabelApp.init().
MetricKit, not a hand-rolled signal handler
A POSIX signal handler has to be async-signal-safe — no malloc, no ARC,
most of the Swift runtime off limits — to avoid crashing harder while
reporting a crash. That's a narrow, easy-to-get-wrong problem real crash
reporters spend thousands of lines getting right. MetricKit is Apple's
own safe capture mechanism (iOS 13+, no third-party dependency): it hands
CrashReporter an already-symbolicated MXCrashDiagnostic on a later
launch, typically within about a day — the same cadence as Xcode
Organizer's own crash reports. Instant delivery isn't possible this way;
reliable, safe delivery is the trade.
final class CrashReporter: NSObject, MXMetricManagerSubscriber {
static let shared = CrashReporter() // MetricKit holds only a weak
// reference to subscribers —
// this is what keeps it alive
func start() { MXMetricManager.shared.add(self) }
func didReceive(_ payloads: [MXDiagnosticPayload]) { … }
}Each MXCrashDiagnostic becomes one POST /api/v1/crash-reports — title
from exceptionType or signal, stack_trace from
callStackTree.jsonRepresentation(), app_version/os_version/
device_model from metaData, and device_id from
UIDevice.identifierForVendor (a loose correlation id, not the same
identity as the backend's own device tokens). Best-effort — a failed
upload is swallowed, never surfaced to the person holding the phone. See
Dashboard for where these end up.

