# Decision Tree: Should You Build This Architecture? 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.