---
layout: ../layouts/DocLayout.astro
title: Architecture
toc: true
---

# Architecture

## Public model

`deskctl` is a thin, non-interactive X11 control primitive for agent loops.
The public flow is:

- diagnose with `deskctl doctor`
- observe with `snapshot`, `list-windows`, and grouped `get` commands
- wait with grouped `wait` commands instead of shell `sleep`
- act with explicit selectors or coordinates
- verify with another read or snapshot

The tool stays intentionally narrow. It does not try to be a full desktop shell
or a speculative Wayland abstraction.

## Client-daemon architecture

The CLI talks to an auto-managed daemon over a Unix socket. The daemon keeps
the X11 connection alive so repeated commands stay fast and share the same
session-scoped window identity map.

Each CLI invocation sends one request, reads one response, and exits.

## Runtime contract

Requests and responses are newline-delimited JSON (NDJSON) over a Unix socket.

All commands share the same JSON envelope:

```json
{
  "success": true,
  "data": {},
  "error": null
}
```

For window payloads, the public identity is `window_id`, not an X11 handle.
That keeps the contract backend-neutral even though the current support
boundary is X11-only.

The complete stable-vs-best-effort policy lives on the
[runtime contract](/runtime-contract) page.

## Sessions and sockets

Each session gets its own socket path, PID file, and live window mapping.

Public socket resolution order:

1. `--socket`
2. `DESKCTL_SOCKET_DIR/{session}.sock`
3. `XDG_RUNTIME_DIR/deskctl/{session}.sock`
4. `~/.deskctl/{session}.sock`

Most users should let `deskctl` manage this automatically. `--session` is the
main public knob when you need isolated daemon instances.

## Diagnostics and failure handling

`deskctl doctor` runs before daemon startup and checks:

- display/session setup
- X11 connectivity
- basic window enumeration
- screenshot viability
- socket directory and stale-socket health

Selector and wait failures are structured in `--json` mode so clients can
recover without scraping text.

## Backend notes

The backend is built around a `DesktopBackend` trait and currently ships with
an X11 implementation backed by `x11rb`.

The important public guarantee is not "portable desktop automation." The
important guarantee is "a correct and unsurprising Linux X11 runtime contract."

## X11 support boundary

This phase supports Linux X11 only.

That means:

- EWMH/window-manager properties matter
- monitor naming and some ordering details are best-effort
- Wayland and Hyprland are out of scope for the current contract

The runtime documents those boundaries explicitly instead of pretending the
surface is broader than it is.