Skip to content

Commit 465cc90

Browse files
wwwillchenwwwillchen-bot
wwwillchen
and
wwwillchen-bot
authored
Add cross-platform ADRs and xplat planning doc (#2737)
## Summary - Add ADR 0001 for host capability interface decisions. - Add ADR 0002 for cloud runtime topology and ADR 0003 for authz model. - Add ADR index and architecture updates for cross-platform planning. - Add desktop/mobile/web unification plan document in plans/. ## Test plan - npm run fmt - npm run lint:fix - npm run ts 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- devin-review-badge-begin --> --- <a href="https://app.devin.ai/review/dyad-sh/dyad/pull/2737" target="_blank"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1"> <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open with Devin"> </picture> </a> <!-- devin-review-badge-end --> --------- Co-authored-by: wwwillchen-bot <theodorewilsonchen@gmail.com>
1 parent 05d5a50 commit 465cc90

File tree

5 files changed

+972
-0
lines changed

5 files changed

+972
-0
lines changed

‎docs/adrs/0001-host-capability-interface.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# ADR-0001: Host Capability Interface
2+
3+
- Status: Proposed
4+
- Date: 2026-02-15
5+
- Owners: Platform Core
6+
- Related plan: `plans/desktop-mobile-web-unification.md`
7+
8+
## Context
9+
10+
Dyad currently routes privileged actions through Electron IPC (`src/preload.ts`, `src/ipc/types/*`, `src/ipc/handlers/*`). This tightly couples product logic to desktop-only primitives:
11+
12+
- local filesystem access
13+
- local process execution
14+
- local git and shell operations
15+
- desktop-only OS/system APIs
16+
17+
Web and mobile clients cannot reuse this runtime model directly. We need one product core that can run against multiple execution hosts:
18+
19+
- desktop local host
20+
- cloud host
21+
22+
## Decision
23+
24+
Adopt a host capability interface as the canonical execution boundary for privileged operations.
25+
26+
The shared product core will depend on a `HostProvider` contract, not directly on Electron IPC channels or HTTP endpoints.
27+
28+
### Interface shape
29+
30+
`HostProvider` exposes capability groups:
31+
32+
- `project`: read/write/rename/delete/list/search file operations
33+
- `exec`: run/stop commands, stream logs/output
34+
- `git`: branch/commit/status/sync operations
35+
- `preview`: start/stop/status/getPreviewUrl
36+
- `integration`: provider-specific operations (supabase/vercel/neon/mcp)
37+
- `system`: optional host/system functions (open external URL, show in folder, clipboard/screenshot)
38+
- `session`: session cache/state controls
39+
40+
Each operation must include a standard envelope:
41+
42+
- `workspaceId`
43+
- `projectId`
44+
- `requestId`
45+
- `idempotencyKey`
46+
- `actor` (user/system/assistant)
47+
- `timestamp`
48+
49+
Each operation returns:
50+
51+
- success payload OR typed error payload
52+
- `correlationId` for tracing
53+
54+
### Streaming model
55+
56+
Streaming operations must follow a uniform event contract:
57+
58+
- `start`
59+
- `chunk`
60+
- `end`
61+
- `error`
62+
63+
Desktop provider maps this to IPC streams; cloud provider maps this to WebSocket/SSE streams.
64+
65+
### Capability negotiation
66+
67+
Hosts must declare supported capabilities at runtime (for example `supportsProcess`, `supportsNativeDialogs`, `supportsShowItemInFolder`), and UI/features must gate behavior accordingly.
68+
69+
## Consequences
70+
71+
### Positive
72+
73+
- Enables shared domain logic across desktop/web/mobile.
74+
- Prevents transport-specific logic from leaking into features.
75+
- Creates deterministic observability across hosts.
76+
- Simplifies adding future hosts.
77+
78+
### Negative
79+
80+
- Requires incremental refactor of existing IPC handlers and call sites.
81+
- Adds short-term complexity with compatibility adapters.
82+
- Requires strict contract/version governance.
83+
84+
## Alternatives Considered
85+
86+
### A. Keep Electron IPC as primary and build web/mobile translators
87+
88+
Rejected because it preserves desktop coupling and creates brittle emulation layers.
89+
90+
### B. Build separate APIs per platform
91+
92+
Rejected because it duplicates business logic and causes long-term behavior drift.
93+
94+
### C. Move everything to cloud and remove local mode
95+
96+
Rejected for now because it breaks existing local-first desktop workflows.
97+
98+
## Rollout Plan
99+
100+
1. Introduce interface and adapter layers in shared packages.
101+
2. Wrap desktop local flows with `ElectronLocalHostProvider`.
102+
3. Migrate critical flows first: chat stream, response apply, app run/stop, git core.
103+
4. Enforce host capability checks in UI.
104+
5. Add `CloudHostProvider` for desktop cloud mode, then web/mobile.
105+
106+
## Acceptance Criteria
107+
108+
- Desktop local mode behavior remains functionally equivalent on migrated flows.
109+
- At least one end-to-end flow runs through both providers with identical domain behavior.
110+
- Stream contracts are transport-agnostic and versioned.
111+
112+
## Open Questions
113+
114+
1. Should integration-specific capabilities be in `integration.*` or split into first-class capability groups?
115+
2. What is the minimum backward compatibility window for provider contract versions?

‎docs/adrs/0002-cloud-runtime-topology.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# ADR-0002: Cloud Runtime Topology
2+
3+
- Status: Proposed
4+
- Date: 2026-02-15
5+
- Owners: Runtime Services
6+
- Related plan: `plans/desktop-mobile-web-unification.md`
7+
8+
## Context
9+
10+
Web and mobile clients need privileged execution capabilities that currently exist only in Electron main process:
11+
12+
- filesystem mutation
13+
- command/process execution
14+
- git operations
15+
- preview lifecycle management
16+
17+
These capabilities require a secure multi-tenant backend architecture with strong isolation, streaming support, and auditability.
18+
19+
## Decision
20+
21+
Adopt a control-plane + worker-plane topology.
22+
23+
### Control plane
24+
25+
Services:
26+
27+
- `api-gateway`: external API entry, auth verification, rate limiting
28+
- `workspace-service`: workspace/project metadata and permissions
29+
- `operation-orchestrator`: validates and queues privileged operations
30+
- `stream-broker`: fan-out for operation events and chat/runtime streams
31+
- `audit-service`: immutable operation/audit log ingestion
32+
33+
### Worker plane
34+
35+
Services:
36+
37+
- `runtime-scheduler`: allocates isolated runtime instances
38+
- `runtime-worker`: executes filesystem/command/preview operations per project
39+
- `git-worker`: executes git operations in isolated workspaces (can be separate or embedded initially)
40+
41+
### Data plane
42+
43+
- relational store for control metadata (workspaces, projects, operations)
44+
- object storage for snapshots/artifacts/log archives
45+
- secret vault for credentials (never persisted in plain metadata tables)
46+
47+
## Isolation and Security Constraints
48+
49+
- Strong tenant isolation at runtime instance boundary.
50+
- Project execution roots are sandboxed per runtime instance.
51+
- Command execution must run with deny-by-default security policies.
52+
- Network egress policy controls by workspace/project tier.
53+
- Every privileged operation must emit an auditable event with actor, scope, and result.
54+
55+
## Streaming and Execution Semantics
56+
57+
- Operations are asynchronous with queued execution where needed.
58+
- Each operation emits typed lifecycle events: `queued`, `started`, `chunk`, `completed`, `failed`.
59+
- Clients reconnect using `correlationId` and replay cursor.
60+
- Idempotency keys prevent duplicate writes on retries.
61+
62+
## Region and Availability Strategy
63+
64+
Initial:
65+
66+
- single region deployment with disaster recovery backups
67+
- active-passive failover for control services
68+
69+
Follow-up:
70+
71+
- multi-region runtime placement
72+
- project region pinning for data residency and latency
73+
74+
## Consequences
75+
76+
### Positive
77+
78+
- Enables web/mobile execution with desktop-comparable capabilities.
79+
- Separates policy/orchestration from execution for safer scaling.
80+
- Supports consistent observability and auditing.
81+
82+
### Negative
83+
84+
- Operational complexity and infra cost increase.
85+
- Requires robust SRE, security, and incident response maturity.
86+
- Cold starts and queue latency can degrade UX if not controlled.
87+
88+
## Alternatives Considered
89+
90+
### A. Single monolithic runtime service
91+
92+
Rejected because it mixes orchestration and execution concerns, making scaling and security controls harder.
93+
94+
### B. Fully serverless per-operation execution only
95+
96+
Rejected because long-lived previews and streaming command output need persistent runtime context.
97+
98+
### C. Desktop relay model (browser/mobile tunnel into user desktop)
99+
100+
Rejected for v1 due to reliability, availability, and connectivity constraints.
101+
102+
## Rollout Plan
103+
104+
1. Build minimal control plane and runtime worker for file ops + command execution.
105+
2. Add stream broker and reliable event replay.
106+
3. Add preview lifecycle management and runtime pooling.
107+
4. Add git worker path and integration-specific execution policies.
108+
5. Introduce multi-region strategy after stable single-region operations.
109+
110+
## Acceptance Criteria
111+
112+
- Cloud project can execute core file and command operations with audited traces.
113+
- Stream reliability meets defined SLOs under target concurrency.
114+
- Isolation and security checks pass internal and external reviews.
115+
116+
## Open Questions
117+
118+
1. Should git run in dedicated workers from day one, or inside runtime workers initially?
119+
2. What runtime class tiers are required for cost/performance segmentation at beta launch?

‎docs/adrs/0003-authentication-authorization-model.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# ADR-0003: Authentication and Authorization Model
2+
3+
- Status: Proposed
4+
- Date: 2026-02-15
5+
- Owners: Platform Security
6+
- Related plan: `plans/desktop-mobile-web-unification.md`
7+
8+
## Context
9+
10+
A multi-platform Dyad requires remote privileged execution. This introduces security requirements not present in desktop-only local mode:
11+
12+
- user identity across devices
13+
- workspace-level access control
14+
- operation-level authorization and consent
15+
- secure storage and use of provider secrets
16+
- end-to-end auditing for sensitive actions
17+
18+
## Decision
19+
20+
Adopt an identity-first model using OIDC authentication, workspace RBAC authorization, and policy-gated privileged operations.
21+
22+
## Authentication Model
23+
24+
- Use OIDC/OAuth2 for user authentication across desktop/web/mobile.
25+
- Use short-lived access tokens and rotatable refresh tokens.
26+
- Desktop, web, and mobile clients use platform-appropriate secure token storage.
27+
- Service-to-service communication uses mTLS and signed service identities.
28+
29+
## Authorization Model
30+
31+
### Workspace RBAC
32+
33+
Base roles:
34+
35+
- `owner`
36+
- `admin`
37+
- `editor`
38+
- `viewer`
39+
40+
Permissions are evaluated against:
41+
42+
- workspace
43+
- project
44+
- operation type
45+
- host capability
46+
47+
### Operation policy layer
48+
49+
In addition to RBAC, high-risk operations require policy checks:
50+
51+
- destructive file deletes
52+
- destructive SQL
53+
- force push/history rewrite
54+
- shell commands outside safe policy
55+
56+
Policy outcomes:
57+
58+
- allow
59+
- require user approval
60+
- deny
61+
62+
## Secrets Model
63+
64+
- Provider credentials stored in centralized secret vault.
65+
- Secrets encrypted with envelope encryption (KMS-managed keys).
66+
- Secrets scoped minimally (workspace/project/provider).
67+
- Runtime workers receive short-lived scoped secret grants, not raw long-lived credentials.
68+
- Secret access events are fully audited.
69+
70+
## Audit and Compliance Requirements
71+
72+
Every privileged operation must log:
73+
74+
- actor id
75+
- workspace/project scope
76+
- operation type
77+
- policy decision
78+
- result status
79+
- correlation id
80+
- timestamp
81+
82+
Audit logs must be immutable and queryable for incident response.
83+
84+
## Consequences
85+
86+
### Positive
87+
88+
- Unified identity and access model across all platforms.
89+
- Defense-in-depth for privileged cloud operations.
90+
- Clear compliance and forensic posture.
91+
92+
### Negative
93+
94+
- Higher implementation complexity than simple API key auth.
95+
- Requires policy engine ownership and ongoing governance.
96+
- Increased onboarding complexity for workspace/admin concepts.
97+
98+
## Alternatives Considered
99+
100+
### A. API key only auth for clients
101+
102+
Rejected due to poor revocation, weak identity semantics, and high leakage risk.
103+
104+
### B. RBAC only without operation policy layer
105+
106+
Rejected because role permissions alone are too coarse for high-risk operations.
107+
108+
### C. Store all secrets client-side and forward on demand
109+
110+
Rejected because it increases exposure and complicates cross-device continuity.
111+
112+
## Rollout Plan
113+
114+
1. Implement OIDC auth + workspace/session primitives.
115+
2. Introduce baseline RBAC enforcement across API endpoints.
116+
3. Add operation policy engine for high-impact actions.
117+
4. Migrate provider secrets to centralized vault and deprecate legacy paths.
118+
5. Add immutable audit log store and admin audit views.
119+
120+
## Acceptance Criteria
121+
122+
- All cloud API operations require authenticated identity and scoped authorization.
123+
- High-risk operations enforce policy with approval/deny semantics.
124+
- Secret access is scoped, short-lived, and auditable.
125+
- Security testing validates token, RBAC, and policy boundaries.
126+
127+
## Open Questions
128+
129+
1. Do we need custom enterprise SSO/SAML in beta or post-GA?
130+
2. What is the default approval policy for non-destructive command execution?
131+
3. What audit retention period is required by target compliance commitments?

‎docs/adrs/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Architecture Decision Records
2+
3+
This directory stores Architecture Decision Records (ADRs) for major technical decisions.
4+
5+
## ADR List
6+
7+
- [ADR-0001: Host Capability Interface](./0001-host-capability-interface.md)
8+
- [ADR-0002: Cloud Runtime Topology](./0002-cloud-runtime-topology.md)
9+
- [ADR-0003: Authentication and Authorization Model](./0003-authentication-authorization-model.md)
10+
11+
## Status Definitions
12+
13+
- `Proposed`: drafted and under review
14+
- `Accepted`: approved and should guide implementation
15+
- `Superseded`: replaced by a newer ADR
16+
- `Rejected`: considered but not adopted

0 commit comments

Comments
 (0)