Plexydesk: Add architecture overview

2026-03-21T19:32:55Z

Add architecture overview

New page

= Architecture =

PlexyDesk combines a compositor, desktop shell, client libraries, and a custom display protocol into one system.

== High-level model ==
{| class="wikitable"
|-
! Layer
! Role
|-
| Client application
| Creates windows and widgets through PlexyDesk APIs
|-
| <code>libplexyui</code>
| High-level C API for widgets, layout, events, and styling
|-
| <code>libplexycanvas</code>
| Local rendering of widgets, text, layout, and GPU effects
|-
| <code>libplexy</code>
| Protocol and DMA-BUF frame handoff support
|-
| Unix socket protocol
| Communication path between clients and compositor
|-
| <code>plexyshell</code>
| Compositor and desktop shell runtime
|-
| Backend stack
| DRM/KMS, input handling, OpenGL, and compatibility bridge code
|}

== Render flow ==
# A client creates UI using functions from <code>plexy_ui.h</code>.
# The client renders its widget tree locally using <code>libplexycanvas</code>.
# The rendered frame is handed to the compositor using the PlexyDesk protocol and DMA-BUF-backed buffers.
# The compositor composites all visible client surfaces, applies shell chrome and effects, and renders desktop elements such as the dock and menubar.

== Design direction ==
PlexyDesk is not presented as a generic Wayland replacement. The codebase is built around a GPU-first rendering path and a project-specific display protocol, while also carrying active bridge work around Wayland and X11 interoperability.

== Important runtime pieces ==
* <code>src/shells/gnu_liquid/main.cpp</code> is the active compositor runtime entry point described in the Makefile
* <code>src/renderer/</code> contains compositor rendering, background, dock, menubar, shader, and async rendering code
* <code>src/backend/</code> contains DRM and display backend support
* <code>src/input/</code> contains libinput integration and focus policy code
* <code>src/server/</code> contains socket server code for the compositor side of the protocol
* <code>src/wayland/</code> contains bridge and interoperability work including XWM-related files
* <code>src/core/</code> contains shell runtime, event loop, dock manager, and display layout state

== Public API surface ==
The public API is exposed through headers in <code>include/plexy/</code>. In particular, <code>plexy_ui.h</code> documents:
* application lifecycle
* window creation
* widget creation
* flexbox-like layout controls
* styling helpers
* event callbacks
* desktop menubar integration

== Repository structure ==
{| class="wikitable"
|-
! Path
! Notes
|-
| <code>src/</code>
| Main compositor, runtime, renderer, input, backend, and bridge code
|-
| <code>lib/</code>
| Shared client-side support libraries
|-
| <code>include/plexy/</code>
| Public headers for application authors
|-
| <code>examples/</code>
| Small standalone sample applications
|-
| <code>apps/</code>
| Larger experiments such as terminal, browser, clock, and utilities
|-
| <code>tasks/</code>
| Engineering notes and implementation logs
|}

== Development note ==
The Makefile notes that the old <code>src/uikit/</code> code remains in the repository, but is no longer compiled into the compositor. The compositor now consumes the canvas library through the C API instead.

== Related pages ==
* [[Getting Started]]
* [[Developer Guide]]
* [[Examples]]

Architecture - Revision history

Plexydesk: Add architecture overview