Native API Boundaries
Native APIs are where stack decisions stop being aesthetic. If the product depends on an OS capability, choose the stack that gives you the cleanest, policy-compliant path to that capability.
Boundary Examples
| Capability | Preferred family | Why |
|---|---|---|
| SMS parsing on Android | Android native | Permission model, Play policy, background/device behavior |
| Biometric lock for finance data | Native mobile | Platform trust and secure storage |
| File watching across large folders | Desktop shell or CLI | Native file APIs and performance |
| Window management, tray, menus | Desktop shell/native | OS-specific desktop affordances |
| Windows widgets, AppLifecycle, Fluent UI | Windows App SDK | Microsoft platform APIs and WinUI 3 |
| Offline installable forms | PWA | Browser APIs can be enough without native store work |
| Tool execution from AI | AI-native stack | Needs sandboxing and audit, not just API calls |
Abstraction Rule
Use a cross-platform abstraction only when the abstraction covers the core capability in the release path you need. If the feature immediately requires native modules, platform channels, or custom plugins, treat that as native work during planning.
AI Failure Pattern
AI agents often overfit to old examples:
- UWP APIs in WinUI 3 projects.
- Android permission snippets that ignore current Play policy.
- Electron apps with unsafe Node exposure.
- PWA examples without iOS/Safari install caveats.
Record the official docs that override model memory before implementation.