tutti/docs/architecture/desktop-backend-access.md

Desktop Backend Access

This document records the desktop backend access model for tutti. The planned shared business-stream protocol is documented in Business Event Stream.

Decision

tuttid is the local product backend for tutti.

Desktop uses a dual-path model:

• renderer -> tuttid for business capabilities and streaming transports
• renderer -> preload -> main for Electron and OS capabilities

main -> tuttid remains available for a small number of host-assisted flows, but it is not the default business access path.

Why

This model keeps one business authority while improving three areas that are awkward under a main-process relay-only design:

• streaming transports such as WebSocket and SSE
• CLI access to the same local product backend
• desktop feature work that should not require a manual IPC wrapper for every daemon capability

The goal is not to make Electron main irrelevant. The goal is to stop using it as a broad business transport relay.

Ownership Model

tuttid

tuttid owns:

• business rules
• durable local state
• domain workflows
• backend contracts shared by desktop and CLI

main

main owns:

• daemon lifecycle supervision
• loopback endpoint discovery and session-token issuance
• desktop-only logging and diagnostics
• Electron and OS integrations
• host-assisted flows that require both native capability and daemon access

main must not become a second business core.

preload

preload owns the narrow renderer-facing desktop SDK.

It should expose:

• runtime configuration needed to reach the managed local backend
• narrow resolved route helpers for managed transport families when renderer should not assemble route-local WebSocket URLs itself
• explicit host capabilities such as file pickers, window control, shell open, notifications, and similar native actions
• a small number of host-assisted commands when renderer cannot complete the flow alone

It should not expose:

• a generic invoke(channel, payload) surface for ordinary renderer work
• transport policy details beyond the minimum needed to reach the managed local backend

renderer

renderer owns:

• UI
• view state
• direct business calls to tuttid
• direct SSE / WebSocket consumption when the stream is business-facing

Renderer should treat tuttid as the backend and window.tutti as the host capability surface.

Default Routing Rule

When adding or changing a desktop capability, choose the path by responsibility.

Direct renderer -> tuttid

Use for:

• ordinary query and command APIs
• workbench and workspace data
• search, list, get, update, save
• terminal and agent streams
• business event subscriptions

Business event subscriptions and bidirectional business event publishing should follow the shared event-stream contract rather than route-local ad hoc socket payloads.

Direct renderer -> main

Use for:

• file and directory pickers
• shell reveal and shell open
• notifications
• menus, tray, clipboard, window lifecycle, updater
• any capability that requires Electron or OS APIs

Host-assisted renderer -> main -> tuttid

Reserve for flows that require both native host authority and daemon authority in one operation.

Examples:

• choose an export destination, then ask tuttid to write backend-owned data
• open a file or resource whose resolution depends on daemon-owned metadata plus native shell behavior
• choose a host directory, then pass that directory to a host capability that needs explicit filesystem input

These flows should stay explicit and few.

Transport Policy

Desktop transport follows these rules:

• tuttid binds to loopback only
• desktop prefers a managed random loopback port over a fixed public port
• main discovers or allocates the endpoint, then provides renderer with runtime config
• business streaming uses HTTP, SSE, and WebSocket directly where appropriate

This favors a product-style local backend over a desktop-private relay model.

Desktop Capability Classification

The desktop surface should be designed as three explicit capability groups.

Backend Business Capabilities

These belong on the direct renderer -> tuttid path:

• health, availability, and backend bootstrap checks
• workspace catalog queries and mutations
• workbench snapshot load and save
• workspace file listing, search, creation, deletion, and upload flows
• streaming business APIs such as terminal, agent, and event streams

Terminal streams and business event streams are both direct business transports, but they should remain separate protocol surfaces because they serve different semantics.

Workspace file APIs on this path should stay logical-path based, for example /workspace/..., rather than exposing host absolute paths as part of the business contract.

This is the default path for business-facing desktop product behavior.

Host Capabilities

These belong on the direct renderer -> main path through preload:

• system locale and system theme signals
• host-side preference sync needed for Electron-only side effects
• updater state and update actions
• file and directory pickers
• dropped-path resolution
• workspace window display and dashboard display
• shell reveal, shell open, native preview affordances
• window creation, focus, and replacement
• notifications, menu actions, tray, clipboard, and similar Electron or OS APIs

These capabilities should stay explicit on surfaces such as window.tutti.host.*, window.tutti.update.*, and window.tutti.platform.*.

Host capability rules:

• host adapters should normalize Electron-native outputs into durable product values before returning to renderer
• host window commands should stay window-oriented and avoid hiding backend mutations inside IPC handlers

Preference ownership rule:

• renderer should read and write user desktop preferences through tuttid
• main should stay limited to system-environment inputs and host-only effects such as theme application

Host-assisted Compound Flows

These belong on the renderer -> main -> tuttid path:

• resolve and open a local file whose authority crosses daemon metadata and host shell behavior
• read local preview content when host file access is still part of the product contract

Use this path when host absolute-path resolution is required at runtime. Do not push that resolution into the workspace catalog or ordinary business DTOs.

These flows should stay narrow, named, and intentional. They are not a second business transport layer.

Update capability rule:

• preload-facing update configuration remains a typed contract, so main/update/* should validate supported channel and policy values instead of silently coercing unknown fields

Security Constraints

Moving business traffic to managed loopback requires explicit guardrails:

• bind only to 127.0.0.1 or equivalent loopback
• prefer random allocated ports over fixed defaults
• require explicit desktop-issued authentication or capability material for renderer-visible backend access
• keep untrusted content, external webviews, and arbitrary browser surfaces off the desktop backend path
• keep preload surfaces narrow even when renderer can talk to tuttid

Renderer visibility of a local backend is acceptable only when the backend is treated as a real product surface, not as an unguarded internal helper.

CLI Relationship

This model supports a cleaner CLI story:

• CLI talks to tuttid as a client of the same local product backend
• desktop renderer talks to the same backend
• main stays a host supervisor, not a CLI dependency

That shared backend contract should reduce duplication across desktop, CLI, and tests.