Dyad Universal Platform Plan (Desktop + Web + Mobile)

Generated by swarm planning workflow on 2026-02-15

Summary

Evolve Dyad from a desktop-only Electron runtime into a multi-platform product with one core experience available on desktop, web, and mobile. Preserve Dyad's local-first strengths on desktop while introducing a secure cloud execution runtime that powers equivalent capabilities on web/mobile where local process and filesystem access are unavailable. Deliver this in phased releases with strict compatibility, observability, and rollback controls.

Problem Statement

Dyad's architecture currently assumes a privileged local host (Electron main process) that can mutate files, spawn processes, run git/npm/docker, handle native protocol links, and store secrets via OS APIs. That creates three constraints:

1. Users cannot use Dyad from browsers, tablets, or phones.
2. Collaboration and continuity across devices is limited.
3. Product growth depends on desktop installation and local toolchain reliability.

The core user problem is cross-device continuity for AI app building without losing the trust, transparency, and production-grade workflows Dyad already supports.

Product Principles Alignment

This plan explicitly preserves Dyad's principles:

• Backend-Flexible: runtime providers (local host, cloud runtime) are pluggable behind one capability interface.
• Productionizable: generated code remains standard user-owned code; cloud runtime is execution infrastructure, not a proprietary app runtime.
• Intuitive + Power User Friendly: default paths are simplified, advanced knobs remain available per host.
• Transparent Over Magical: every remote execution action is surfaced with logs, diffs, approvals, and host/source labels.
• Bridge, Don't Replace: existing git, npm, Docker, Supabase workflows continue; web/mobile use remote bridges where local host access is impossible.
• Delightful: consistent high-quality interactions across platforms with platform-native ergonomics.

Scope

In Scope (MVP to GA)

• Introduce a host-agnostic execution architecture: LocalHost (desktop) + CloudHost (web/mobile, optional desktop).
• Extract shared product core (domain logic, schemas, query keys, prompts, contract models) into reusable packages.
• Deliver:
  • Desktop app (Electron) with both local and cloud host modes.
  • Web app (browser) using cloud host mode.
  • Mobile app (React Native) using cloud host mode with mobile-specific UX.
• Build secure cloud runtime services for:
  • Project filesystem operations
  • Command/process execution
  • Streaming logs/events/chunks
  • Git operations
  • Secret storage and provider credentials
  • Project/session persistence
• Implement identity, auth, authorization, org/workspace model, and audit trails for remote operations.
• Add deterministic operation model for approvals and replay safety.
• Provide migration tools to import desktop projects into cloud workspaces and export back to local repos.
• Establish full testing matrix (unit/integration/e2e/load/security) across all three clients.

Out of Scope (Initial)

• Full offline web/mobile parity with local process execution.
• Mobile local code execution sandbox equivalent to desktop Node/Docker.
• Real-time multiplayer editing (beyond single-user multi-device continuity).
• Replacing existing desktop local mode as default for current users.

Target Users

1. Existing desktop power users who want optional cloud continuity.
2. New users who want instant web onboarding without installing desktop tooling.
3. Mobile-first users who need monitoring/approval/light editing and AI interaction on the go.
4. Teams needing shared cloud workspaces and centralized auditability.

User Stories

• As a desktop user, I want to keep local mode exactly as today while optionally enabling cloud sync so I can work from any device.
• As a web user, I want to create/import a project and run previews without local setup so I can start immediately.
• As a mobile user, I want to review AI changes, approve/reject actions, and trigger fixes so I can keep momentum away from my laptop.
• As a power user, I want explicit visibility into whether an action runs locally or remotely so I can trust the system.
• As a security-conscious user, I want granular permissions, audit logs, and scoped credentials for all remote operations.

UX Design

Universal IA

Global top-level structure across platforms:

1. Workspace switcher
2. Project list
3. Chat + plan + execution timeline
4. Code/preview/problem surfaces (platform-adapted)
5. Settings (provider + runtime + integrations + security)

Host Awareness UX

Every execution surface displays host source:

• Local Host (Desktop)
• Cloud Host (Region)

Every action card includes:

• actor (user, assistant, system)
• host
• operation type (write, rename, command, git, sql, etc.)
• approval state
• request/correlation ids

Platform-specific UX

Desktop:

• Retain full editor + preview + process console + branch workflows.
• Add host toggle per project (Local, Cloud, Hybrid later).

Web:

• Same interaction model as desktop, minus local-only controls.
• Web-safe file pickers and managed imports.
• Browser-native auth/session management.

Mobile:

• Chat-first and task-first workflow.
• Focus on review/approval, logs, quick edits, plan management, and notifications.
• Optional compact code diff viewer, not full IDE parity in v1.

Key States (All Platforms)

• Default: last opened project, host badge visible.
• Loading: stream-level progress and host-labeled steps.
• Empty: onboarding flows (create/import/connect repo).
• Error: user-actionable messages with host context and retry semantics.
• Degraded: partial capability mode when host lacks permissions.

Accessibility

• Keyboard-first behavior on desktop/web.
• VoiceOver/TalkBack screen reader semantics on mobile.
• Reduced motion settings propagated from platform preferences.
• High contrast, robust focus states, and large touch targets on mobile.

Technical Design

Architecture

Current State (Desktop-only)

• Renderer React app calls contract-generated IPC clients.
• Preload mediates channel allowlist.
• Main process owns privileged capabilities.

Target State (Universal)

Introduce a Host Capability Layer and split concerns:

1. Client Shells
   • Electron desktop shell
   • Web shell
   • Mobile shell
2. Shared Product Core
   • Shared types/schemas/validation
   • Shared domain state machine
   • Shared query key + API contract definitions
   • Shared chat/tag parsing/rendering primitives
3. Host Providers
   • ElectronLocalHostProvider (desktop local)
   • CloudHostProvider (web/mobile + optional desktop)
4. Dyad Cloud Runtime Services
   • Project FS service
   • Exec service
   • Git service
   • Streaming broker
   • Secret service
   • Workspace/project metadata service
   • Telemetry/audit service

Host Capability Interface

Define one canonical interface consumed by shared product logic:

• host.project.readFile/writeFile/rename/delete/list/search
• host.exec.runCommand/stop/streamLogs
• host.git.*
• host.preview.start/stop/getUrl
• host.db.executeSql (or delegated integration service)
• host.secrets.get/set/listScopes
• host.system.openExternal/showInFolder (optional capability)
• host.session.*

Each method includes:

• idempotency key
• actor context
• workspace/project context
• auth context
• correlation id

Transport Strategy

Desktop local:

• Existing IPC transport remains.
• Gradual migration from raw channel usage to host interface adapter.

Web/mobile:

• HTTPS + WebSocket/SSE for RPC + stream channels.
• Unified event model mirroring IPC stream contracts.

Data Model Changes

Introduce platform-neutral IDs and workspace ownership:

• workspaces
• projects
• project_hosts (local/cloud binding + capabilities)
• sessions
• operations
• operation_logs
• credentials (scoped/rotatable/encrypted)
• runtime_instances

Desktop local DB remains for local-only metadata and cache; cloud state is source of truth for cloud projects.

Security Model

• OAuth/OIDC sign-in with device session management.
• Workspace RBAC (owner, admin, editor, viewer).
• Operation policy engine for dangerous actions.
• Explicit consent model for high-impact operations (rm, destructive SQL, force push).
• Secret encryption with KMS/HSM-backed envelope keys.
• Signed short-lived runtime tokens.
• Tenant isolation at filesystem + process + network layers.
• Full audit trail for every remote privileged operation.

Preview/Runtime Model

• Desktop local preview uses existing local process workflow.
• Cloud preview runs in isolated runtime instances (container/sandbox).
• Preview URLs proxied through policy-aware gateway for script injection and security headers.
• Mobile/web connect to the same preview stream endpoints and event bus.

Compatibility Strategy

• Keep existing desktop local paths functional behind adapters during migration.
• Contract compatibility versioning:
  • v1: legacy IPC contracts
  • v2: host API contracts
• Dual-write and read-fallback for transitional metadata.

Components Affected

Desktop Existing Areas (Refactor Required)

• src/main.ts — split shell bootstrap from capability execution wiring.
• src/preload.ts + src/ipc/preload/channels.ts — transition to host adapter entrypoints.
• src/ipc/contracts/core.ts + src/ipc/types/* — extract reusable contract/core package.
• src/ipc/handlers/* — split into:
  • local provider implementations
  • shared domain orchestration handlers
• src/ipc/processors/response_processor.ts — host-agnostic operation application engine.
• src/ipc/handlers/chat_stream_handlers.ts — move stream orchestration into shared domain + host-specific execution delegates.
• src/main/settings.ts — evolve to multi-host config model.
• src/db/* — local cache role clarification and migration helpers.

New Package/Module Structure (Proposed)

• packages/core-domain/
  • state machines
  • operation orchestration
  • validation and policies
• packages/contracts/
  • shared contract schemas (zod/openapi derivation)
• packages/client-sdk/
  • web/mobile/desktop transport adapters
• packages/ui-shared/
  • cross-platform primitives and design tokens
• apps/desktop-electron/
• apps/web/
• apps/mobile/
• services/runtime-api/
• services/runtime-worker/
• services/git-api/
• services/ops-audit/

Mobile Stack Recommendation

• React Native + Expo (or bare RN if native modules become mandatory quickly).
• Reuse shared domain + contracts + query/state logic.
• Native-only wrappers for push notifications, secure storage, deep links.

Web Stack Recommendation

• React + TanStack Router/Query shared with desktop where possible.
• SSR optional; start with SPA + API gateway.
• Progressive enhancement for heavier features.

Implementation Plan

Phase 0: Alignment, Constraints, and Success Contracts

• Define platform parity goals by feature tier (Core, Advanced, Desktop-only).
• Publish cross-platform capability matrix with explicit non-goals.
• Finalize SLOs for cloud runtime (p95 latency, stream reliability, runtime startup time).
• Define compliance/security baseline (SOC2 controls, secret handling, audit retention).
• Create architecture decision records (ADRs) for host interface and cloud runtime topology.

Exit criteria:

• Stakeholder signoff on scope and phased parity guarantees.
• Measurable release gates approved.

Phase 1: Monorepo Restructure and Shared Core Extraction

• Create packages/contracts from src/ipc/contracts + src/ipc/types.
• Create packages/core-domain for shared orchestration logic.
• Move shared schema utilities out of Electron-only folders.
• Introduce platform-agnostic logger, event model, and error taxonomy.
• Keep desktop app compiling via compatibility wrappers.

Exit criteria:

• Desktop builds unchanged behavior behind wrappers.
• Shared packages consumed by desktop with zero functional regression in e2e smoke suite.

Phase 2: Host Capability Layer on Desktop

• Implement ElectronLocalHostProvider that wraps existing handlers.
• Route key flows (chat stream, response apply, run app, git) through host interface.
• Add capability negotiation mechanism (supportsProcess, supportsNativeDialogs, etc.).
• Instrument host operation timings and failures.

Exit criteria:

• Desktop local mode fully driven through host abstraction.
• Legacy direct paths removed for migrated flows.

Phase 3: Cloud Runtime Foundation

• Build runtime-api service with authn/authz + workspace/project model.
• Build runtime-worker for isolated filesystem/process execution.
• Implement operation queue, idempotency, and stream broker.
• Introduce cloud secret vault integration.
• Implement project persistence and snapshot strategy.

Exit criteria:

• Can create cloud project, write/read files, run command, stream logs via API.
• End-to-end audited operations with trace ids.

Phase 4: Cloud Host Provider + Desktop Cloud Mode

• Implement CloudHostProvider SDK in client packages.
• Add desktop runtime mode toggle (Local, Cloud).
• Support project import/sync between local and cloud.
• Add conflict resolution strategy for divergent histories.
• Add host badges and per-action host attribution in UI.

Exit criteria:

• Desktop can operate entirely against cloud host for selected projects.
• Existing local workflows remain stable.

Phase 5: Web App MVP

• Create apps/web shell using shared core/domain/contracts.
• Implement auth/session/bootstrap flows.
• Integrate cloud host provider for project/chat/preview workflows.
• Add browser-safe file import flows.
• Deliver first web e2e suite with parity against desktop cloud mode for core flows.

Exit criteria:

• Web supports create/import project, prompt->apply, preview, git basic operations.

Phase 6: Mobile App MVP

• Create apps/mobile shell with shared domain and cloud provider.
• Implement mobile chat + approvals + timeline + lightweight diff view.
• Add push notifications for long-running operations and approval requests.
• Add mobile-friendly preview handoff (deep link to preview URL/webview).
• Harden reconnect/resume behavior on app backgrounding.

Exit criteria:

• Mobile supports review/approve/change-request workflows and basic prompting on cloud projects.

Phase 7: Integration Hardening (Git, Supabase, Vercel, MCP)

• Move integration handlers behind host/service boundaries.
• Define cloud-safe equivalents for local shell-dependent tasks.
• Add provider-level policy controls and rate limits.
• Add integration fallback messaging when host lacks specific capability.

Exit criteria:

• Core integrations function consistently across desktop cloud/web/mobile.

Phase 8: Data Migration and Interop

• Build desktop migration assistant:
  • project selection
  • credential remapping
  • dry-run diff
  • import execution
• Build export assistant from cloud project to local git repo.
• Implement reversible migration metadata for rollback.

Exit criteria:

• User can migrate a desktop project to cloud and back with deterministic results.

Phase 9: Security, Compliance, and Abuse Protection

• Threat model all privileged cloud operations.
• Add abuse limits (process quotas, network egress policy, command allow/deny policies).
• Add malware/exfiltration safeguards in runtime sandboxes.
• Complete security penetration test and incident response runbooks.

Exit criteria:

• Security review gates passed for public web/mobile beta.

Phase 10: Observability, Reliability, and Cost Controls

• Distributed tracing across client -> API -> worker.
• Runtime utilization dashboards and budget guardrails.
• Auto-scaling + cold-start mitigation strategies.
• SLO-based alerting and on-call playbooks.

Exit criteria:

• Runtime meets agreed SLOs under synthetic and beta traffic.

Phase 11: GA Rollout

• Controlled alpha (internal), private beta, public beta, GA.
• Feature flags by platform and workspace tier.
• In-app education and migration guides.
• Post-GA stabilization sprint and backlog reprioritization.

Exit criteria:

• Multi-platform GA with stable desktop local mode and production-grade cloud mode.

Detailed Change-by-Change Mitigation Matrix

Current Desktop-Tied Change Area	Why It Breaks on Web/Mobile	Planned Solution	Migration Steps	Risks	Mitigations
Electron window lifecycle	Browser/mobile don't expose app-level window control APIs	Abstract window controls as optional capabilities; no-op/alt UX on web/mobile	Add capabilities.system.windowControls checks and branch UI actions	UX inconsistency	Platform-specific UI patterns with explicit affordances
Preload/IPC channel model	No contextBridge outside Electron	Replace IPC with shared host API transport adapters	Build client-sdk with IPC adapter + HTTP/WS adapter	Contract drift	Shared contract package + compatibility tests
Direct FS mutation (fs, recursive ops)	Browser sandbox and mobile filesystem constraints	Move FS ops to cloud runtime service for web/mobile	Route all file ops through host provider interface	Latency, partial failures	Operation queue + optimistic UI + retry/idempotency
Local process spawn (spawn, npm, pnpm, docker)	Impossible in browser and limited on mobile	Cloud execution workers provide command runtime	Map command operations to runtime API endpoints	Multi-tenant security	Sandbox isolation, policy engine, egress restrictions
Local git binaries and repo operations	Browser/mobile lack full git CLI integration	Cloud git service + optional libgit implementation	Wrap existing git utils behind host provider	Repo corruption/conflicts	Transactional git ops + snapshot + conflict UI
Local SQLite + settings files	Different storage semantics across platforms	Split metadata: cloud source of truth + local cache	Introduce workspace/project cloud schema and cache layer	Data divergence	Versioned sync protocol + conflict resolution policies
safeStorage OS secret encryption	Not portable to web runtime	Centralized secret vault + device secure storage for tokens	Migrate secrets to scoped vault entries	Secret exposure	KMS encryption, short-lived tokens, RBAC + audit
dyad:// protocol deep links	Different deep-link systems per platform	Unified auth/deeplink router abstraction	Implement desktop protocol + web redirect + mobile deep links	Auth loop bugs	End-to-end deep-link integration tests
Auto-update packaging model	Web/mobile release channels differ	Per-platform release orchestration	Desktop keeps auto-update; web CI deploy; mobile app-store release tracks	Version skew	API contract version checks + forced upgrade gates
Clipboard/screenshot/system dialogs	Limited browser/mobile APIs	Capability-based action model with platform fallbacks	Add capabilities.system.* gating and alternate UX	Missing features confusion	UI labels for unavailable actions + docs
Node PATH / environment probing	Not meaningful in web/mobile	Host-specific environment diagnostics	Keep on desktop only; cloud diagnostics endpoints for remote runtime	Support complexity	Host-tagged diagnostics bundle
Local preview proxy assumptions	Remote preview URLs and CORS/security differences	Cloud preview gateway + signed access tokens	Refactor preview proxy to support remote sources	Security headers misconfig	Security review + automated integration checks
Local-only backup/reset semantics	Cloud data is multi-tenant and persistent	Cloud snapshot/restore service	Replace destructive reset with scoped project reset endpoints	Accidental data loss	Confirmation gates + point-in-time restore
Existing e2e Electron-only test harness	No coverage for web/mobile runtime paths	Multi-platform CI matrix and contract tests	Add web playwright, mobile detox/appium flows, shared contract test suite	Test explosion	Risk-based test pyramid + shared fixtures

API and Contract Evolution Plan

Contract Versions

• Host API v1:
  • project/file operations
  • command execution
  • stream channels
  • git subset
  • preview lifecycle
• Host API v2 (follow-up):
  • advanced integration capabilities
  • multi-user collaboration hooks

Compatibility Policy

• Additive changes only within minor versions.
• Breaking changes require version bump + dual support window.
• Desktop app ships bridge adapters for at least two server versions.

Rollout and Migration Strategy

User Cohorts

1. Internal team
2. Existing pro desktop users (opt-in cloud mode)
3. New web users
4. Mobile beta users

Migration Controls

• Feature flags by account and project.
• Per-project host mode with explicit migration wizard.
• Import/export dry-run and validation.
• One-click rollback to prior stable mode during beta.

Testing Strategy

Unit

• Host capability interface contract tests.
• Operation policy tests (approval/denial paths).
• Idempotency and retry behavior tests.
• Schema/version compatibility tests.

Integration

• Desktop local provider tests.
• Cloud provider API workflow tests.
• Git and command runtime execution tests.
• Secret vault permission boundary tests.

E2E

• Desktop local and desktop cloud parity scenarios.
• Web end-to-end core workflows.
• Mobile approval/chat/review flows.
• Cross-device continuity scenarios.

Performance/Load

• Runtime cold start and warm path benchmarks.
• Stream throughput and latency under load.
• Command queue saturation and backpressure behavior.

Security

• Authn/authz penetration tests.
• Tenant isolation red-team tests.
• Command injection and path traversal tests.
• Secret leakage and audit trail validation.

Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
Cloud runtime complexity delays schedule	High	High	Phase gates, strict MVP slice, dedicated platform team
Desktop regressions during refactor	Medium	High	Adapter-first migration, dual-path fallbacks, heavy regression e2e
Security incident in remote execution	Medium	High	Defense-in-depth sandboxing, policy engine, external security review
Cost overrun for cloud execution	High	Medium	Quotas, metering, auto-hibernate, runtime class tiers
Poor mobile UX if desktop parity is forced	Medium	Medium	Mobile-native scope (review/approval first), defer full IDE parity
Data migration failures	Medium	High	Dry-run validation, reversible migrations, snapshot restore
API version drift across clients	Medium	Medium	Shared contracts package, CI compatibility gates
Adoption confusion (local vs cloud modes)	Medium	Medium	Clear host labels, onboarding decision guides, safe defaults

Success Metrics

Product:

• Web activation rate (project created within first session).
• Cross-device retention (users active on 2+ platforms weekly).
• Mobile approval completion rate.
• Time-to-first-preview on web.

Reliability:

• Runtime startup p95.
• Stream interruption rate.
• Operation failure rate per capability.
• Incident count/severity.

Business:

• Conversion uplift from web funnel.
• Pro retention for users adopting cloud mode.
• Infrastructure cost per active cloud project.

Team Topology and Ownership

• Platform Core Team: host abstraction, shared packages, contract evolution.
• Runtime Services Team: cloud execution, security, scaling.
• Client Experience Team:
  • Desktop stream
  • Web stream
  • Mobile stream
• Integrations Team: git/supabase/vercel/mcp cross-host support.
• QA/Release Team: matrix testing + staged rollout orchestration.

Delivery Timeline (Indicative)

• Q1: Phases 0-2 (foundation + desktop host layer)
• Q2: Phases 3-4 (cloud runtime + desktop cloud mode)
• Q3: Phase 5 (web MVP) + phase 7 partial
• Q4: Phase 6 (mobile MVP) + phases 8-10
• Q1 next year: Phase 11 GA stabilization

Open Questions

1. Should web/mobile be Pro-only at launch or include free tier with strict quotas?
2. Do we want per-project region pinning for data residency in v1?
3. Is mobile expected to support direct code editing beyond diff comments in v1?
4. Which integrations are mandatory for web GA (GitHub, Supabase, Vercel, MCP)?
5. What SLA/uptime commitments are required before public GA?
6. Should cloud projects support collaborative multi-user editing in the first year, or remain single-user with sharing only?