Shared business logic should describe what the product is trying to do, not which native SDK method or platform exception happens to implement it. Keep device mechanics behind a clear capability boundary.
This does not require hiding real platform differences. Expose unsupported or optional capabilities honestly so shared code can make valid decisions without inspecting native internals.
Define intent in product language
Use operations such as capture attachment, request location, or export report with explicit inputs, outcomes, ownership, and failure categories. Avoid making shared rules depend on an activity reference, raw native path convention, or platform-specific error string.
Flutter's current architecture guide and native integration reference provide complementary context for responsibility and transport boundaries.
Separate a fictional proof-of-visit rule
Suppose a business workflow requires a report with an accepted location reading and a photo. The shared rule determines what evidence qualifies and whether the report may be submitted. Native adapters obtain the location and image under each platform's permissions and lifecycle.
Test supported capability, denied permission, unavailable sensor, cancelled capture, stale result, and account change. Shared tests can use controlled capability outcomes, while native integration tests verify the real platform maps to those meanings correctly.
Do not let a platform's convenient success value bypass the business rule. A location result may exist but fail the workflow's freshness or accuracy requirement. Those conditions belong in an explicit product contract, with appropriate evidence and limitations.
Keep exceptions discoverable rather than scattered
If one platform cannot meet a requirement, expose that capability state and provide the agreed alternative. Avoid dozens of platform checks inside unrelated widgets, which make future changes difficult to trace.
At the same time, do not create a giant universal service that owns every native feature and business decision. Keep boundaries focused on capabilities with coherent lifecycle and consumers.
The tradeoff is abstraction effort versus change independence. A small adapter can isolate a volatile SDK without overengineering. Too much indirection can make a simple call difficult to understand, while no boundary can spread native assumptions throughout the app.
The Social App case study documents work spanning Flutter, native Swift and Kotlin context, backend systems, and architecture evolution. This proof-of-visit workflow is fictional and does not describe its implementation.
Questions about shared and native logic
Should shared code know the operating system?
Only where that knowledge is necessary to product behaviour. Prefer explicit capabilities when they describe the requirement more accurately.
Can all errors share one failure value?
Only if recovery is genuinely identical. Permission denial, cancellation, unsupported hardware, and transient failure often need different actions.
What should a review inspect first?
Trace one business rule through its capability contract and both native implementations. Bring leaked assumptions to a Flutter architecture discussion.