# AetherDesk Desktop Architecture

AetherDesk is an all-in-one AI PC: a visual desktop, an app/tool registry, a window runtime, a native packaging target, and a governed local execution system. The order matters.

## Build Order

### Phase 1: Layers 1-3 Together

Build the working desktop before wrapping it.

1. Desktop Shell
2. App Registry
3. Window Runtime

These three layers are one unit because the user experience only makes sense when the desktop, apps, and windows agree. A Start menu without a registry becomes clutter. A registry without a runtime becomes a list. A runtime without a shell becomes invisible machinery.

### Phase 2: Layer 4 By Itself

Package only after the desktop contract is stable.

4. Native Wrapper

Electron or Tauri should wrap the existing AetherDesk contract. The wrapper must not redefine the security model, hardcode secrets, invent a second app registry, or make raw host shell access easier than the browser version.

### Phase 3: Layers 5-6 Together

Harden actions and proof together.

5. Security Layer
6. Receipts

No sensitive action should exist without both a gate and a receipt. Sending, publishing, uploading, deploying, writing host files, changing permissions, or using secrets must have an explicit boundary plus proof.

## Layer 1: Desktop Shell

Purpose: make AetherDesk feel like a real PC surface.

Current surfaces:
- `aetherdesk/public/real-pc-shell.js`
- `aetherdesk/public/real-pc-shell.css`
- `/`
- `/api/desktop/state`
- `/api/desktop/action`

Rules:
- Fresh boot should orient the user without opening noisy windows.
- Taskbar, Start, work modes, desktop groups, snapping, minimize/maximize, and short-screen behavior are first-class.
- The visible desktop should be usable by a human and readable by an AI.

## Layer 2: App Registry

Purpose: make every app/tool addressable from one source of truth.

Current surfaces:
- `/api/desktop/apps`
- `/api/desktop/tool-plane`
- `/api/app-hooks`

Rules:
- New apps must enter through the registry before custom shortcuts.
- Start, taskbar, tool-plane, AI routing, and future packaged plugins must agree on app IDs.
- A visual window is optional; AI should be able to operate tools through the tool-plane when a full window is not needed.

## Layer 3: Window Runtime

Purpose: manage running apps like a real desktop.

Current surfaces:
- `/api/desktop/state`
- `/api/desktop/action`
- `/api/control/snapshot`
- `/api/desktop/tool-plane`

Rules:
- Windows need machine-readable state: open, focused, minimized, maximized, layout, and cell links.
- Connected windows can share context/workflows; separated windows transfer by copy/paste or deliberate drag.
- Visual polish is not enough. The runtime must expose state so AI agents and test harnesses can verify it.

## Layer 4: Native Wrapper

Purpose: make AetherDesk install and run like a desktop app.

Current bridge surfaces:
- `/api/portable-device`
- `/manifest.json`
- `/sw.js`
- `docs/RELEASE_PACKAGING.md`

Candidate wrappers:
- Electron: best for fast Node integration and true embedded browser/webview experiments.
- Tauri: best for a smaller native wrapper once the desktop contract is stable.

Rules:
- Do not start native packaging until layers 1-3 have stable tests.
- The wrapper may provide native windows, menus, filesystem bridges, and process bridges.
- The wrapper must not bypass governance, receipts, or secret boundaries.

## Layer 5: Security Layer

Purpose: protect the user, files, credentials, and future work.

Current surfaces:
- `/api/governance/status`
- `/api/auth/onboarding`
- `/api/connectors`
- `/api/pc/apply-requests`
- `/api/pc/apply-approvals`

Rules:
- Default to read-only.
- Keep secrets out of source, receipts, logs, screenshots, exported builds, and generated package artifacts.
- Use local env/auth stores for user-owned secrets and connector login.
- Block raw host shell, secret values, ungated mutation, send, publish, upload, deploy, and permission changes by default.

## Layer 6: Receipts

Purpose: make action history auditable and resumable.

Current surfaces:
- `/api/receipts`
- `/api/agent/workflows/receipts`
- `/api/pc/apply-receipts`
- `/api/pc/rollback-receipts`
- `/api/system-access/receipts`

Rules:
- Receipts should record the action, gate, decision, result, artifact path, output tail, and next useful recovery detail.
- Receipts must redact secrets.
- Apply receipts and rollback receipts are part of the same trust loop.

## Machine Contract

The architecture is exposed at:

```text
GET /api/desktop/architecture
```

Expected schema:

```text
aetherdesk_desktop_architecture_v1
```

This route is the fast-read contract for AI agents. This Markdown file is the human-readable operating map.
