architecture-fit-check

Architecture Fit Check

One job: catch the wrong-primitive mistake before it costs weeks. The most expensive Apple-platform bugs are usually not bad code — they are the right code on the wrong primitive, where a powerful, opaque framework is bent to a job it was never built for, and the platform answers with failures you cannot observe.

The core principle

Match the primitive to the problem's actual shape, not to an elegant invariant. A property you want — privacy, safety, "it can't leak by construction" — that ordinary app logic keeps cheaply must not be bought with a heavyweight, unobservable mechanism. Prefer the simplest primitive that ships, is debuggable in production, and fails legibly. Build what Apple's own engineers would ship, not a purity machine that cannot deliver.

When to run this

• Before adopting a powerful or opaque Apple framework — the high-tax, hard-to-observe ones with a background reconciler: CloudKit sharing (CKShare) + NSPersistentCloudKitContainer mirroring, NSFileCoordinator / UIDocument, NSFileProviderExtension, Core Data persistent history, App Intents donation graphs, WidgetKit timeline orchestration.
• When a subsystem has survived 3+ fixes and each fix surfaces a new break in a different place (the architectural-failure signal from systematic debugging).
• When the justification for a design is "this makes X structurally impossible" rather than "this does X."
• Reviewing any new sync / sharing / persistence / app-extension subsystem.

The five-question audit

For the framework or primitive under review, answer in writing:

1. What is this primitive's ONE job? State it in a sentence. (e.g. "CKShare = let multiple users co-edit one mutable record graph.")
2. What is my problem's actual shape? Append-only or mutable? One author per record or many? One-way delivery or true co-editing? Request/response or stream?
3. Do (1) and (2) match? If you use under ~10% of the primitive's purpose, you pay full tax for a fraction of fit. Mismatch → stop.
4. Am I adopting this to do a job, or to make something impossible? "Impossible by construction" is a red flag when ordinary app logic keeps the property for free.
5. Can I observe and debug it in production, on a real device? If the failure mode is an opaque background reconciler with no log surface (mirroring delegate, file-coordinator deadlock), that is a deferred outage. Demand observability before adoption.