# 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?
