Decision Tree: Should You Build This Architecture?

May 14, 2026 · View on GitHub

Run the user's project through this tree before recommending the four-layer architecture. It excludes the architecture for many common project shapes, and saying so directly is more useful than over-fitting advice.

Question 1: How many OS targets?

Just one (macOS only, or Windows only): → Don't use this architecture. Build native (Swift/AppKit, or C#/WinUI/WPF). The cross-platform tax is not worth it. The whole point of this stack is to share a UI codebase across OSes; with one OS, you have nothing to share.
Two (macOS + Windows): → Proceed.
Three (+ Linux): → Proceed, but warn: this skill is grounded in macOS+Windows evidence. Linux + WebKitGTK works but has its own quirks not documented here. WebView2 doesn't exist on Linux; you'll likely use WebKitGTK or fall back to bundling. Budget for it.
Mobile too (iOS / Android): → Proceed for desktop, and extract the Rust core to share with mobile (this is exactly the Layer-4-sharing benefit). Don't try to share the React UI with mobile via React Native; that's a different stack with different trade-offs.

Question 2: Is "native feel" actually a hard requirement?

Yes, the app must be indistinguishable from native (e.g., a launcher, a system utility, a productivity tool the user lives in all day): → Proceed.
"It should be nice but Electron is fine": → Don't use this architecture. Use Electron. The polish budget here is 5–10× higher than Electron, and you only earn that back if native-feel is a competitive differentiator. If "nice" is sufficient, the cheapest path is Electron + a good designer.
No, it's an internal tool, no end-user polish needed: → Don't use this architecture. Web app in a browser tab. Or Electron. Or a Mac app for the one OS your team uses.

Question 3: Do you have a plugin/extension ecosystem?

Yes, third parties will build extensions: → JS/TS plugins are the only practical choice (1000× more authors than native plugins). You need Layer 3 (Node backend). Proceed.
No, but the app has very rich business logic / network code: → Layer 3 (Node) is still likely correct, because the alternative is duplicating business logic in Swift and C#. Proceed.
No, and the app is mostly UI + a small amount of native work: → Consider skipping Layer 3. A native shell + WebView + small Rust core may be enough. Lighter, simpler.

Question 4: How tight is your launch budget?

Cold start must be < 100 ms: → Don't use this architecture. The WebView + Node boot floor is ~150–300 ms even with prewarming. Build native.
Cold start < 500 ms acceptable, warm start < 50 ms required: → Proceed. Prewarm a hidden launcher window at app start. Warm activation is essentially free.
Cold start tolerance is generous (< 2s): → Proceed comfortably.

Question 5: What's your memory budget?

Under 150 MB resident: → Don't use this architecture. The floor is ~150 MB on Windows for an empty WebView + Node. Build native.
300–800 MB acceptable: → Proceed.
1 GB+ fine (e.g., a heavy AI app): → Proceed, but consider memory hygiene from day one — see references/05-memory-truths.md. Going over 1 GB sustained will cost you reviews from users who don't understand memory accounting.

Question 6: How experienced is your team?

Strong in one of Swift OR C#, plus React/TS: → Proceed. You'll need to hire/learn the other native side, but the centroid of work is in TS where the team is fluent. This is a near-ideal fit.
Strong in React/TS, no native experience: → Proceed with caution. The two native shells (Layers 1 + 1 again) are real work. Budget 2–3 months per shell for an experienced TS engineer to get competent. Or hire one native specialist per OS.
Strong in native (Swift or C#), no React experience: → Proceed with caution. React/TS is easier to ramp on than the reverse, but design-system maturity in React takes longer than people expect. Budget 3 months for the UI baseline before shipping.
Two-person team, no Rust experience: → Skip Layer 4 initially. Start with shell + WebView + Node. Add Rust only when a specific need arises (file indexer, crypto, etc.). UniFFI is great but ramping on Rust + UniFFI + cross-toolchain builds while shipping is a lot.

Question 7: How long is the runway?

Short (need to ship in < 3 months): → Don't use this architecture. Use Electron or Tauri. You can rewrite to native-feel later if the product takes off. (Raycast itself started as a pure Mac native app — they rewrote after they had product-market fit.)
Medium (6–12 months): → Proceed if you have native experience on the team. Skip Layer 4 to start.
Long (12+ months to v1): → Proceed comfortably. All four layers.

Decision matrix

After all seven questions, score yourself:

Score	Recommendation
All "Proceed"	Four-layer architecture. Read `references/02-architecture.md`.
One or two "Skip Layer X"	Three-layer architecture (omit the skipped layer). Read `references/02-architecture.md` and note the per-layer rationale to confirm what you're losing.
Any "Don't use this architecture"	Use the alternative named in that question (native / Electron / different stack). This skill doesn't apply.
"Proceed with caution" anywhere	Proceed but front-load risk: prototype the riskiest layer first (e.g., the native shell + WebView wiring), not the easiest.

Common false positives (apps that seem like a fit but aren't)

A "fast" web app — i.e., a SaaS dashboard the team wants to "make feel native." Almost always: just ship it as a web app. Adding a native shell for "feel" rarely pays back the engineering cost.
A small utility — e.g., a clipboard manager. Probably wants pure native; the cross-platform value isn't there at this size.
A game or graphics-heavy app — use a game engine or native graphics framework, not a WebView.
A document editor — depends. Notion/Obsidian-class? Maybe. Microsoft Word-class? Native.
A media player — native, because media frameworks (AVFoundation, Media Foundation) are platform-specific anyway.

When this architecture is clearly right

A productivity launcher (Raycast, Alfred-style).
A note-taking app with rich extensions (Obsidian-class).
A team communication app with deep OS integration (Slack-class, if willing to invest more than Slack did).
A developer tool that needs to embed editors, terminals, and rich panels (Linear desktop, Warp-ish).
An AI app where the UI needs to render rich markdown/code and the backend needs to manage long-lived AI sessions across windows.

If the user's project resembles one of these and they passed Q1–Q7, recommend with confidence.