Service Architecture

The interface is not privileged

The Lazarus GTK interface is a service client. It does not link the recovery core and cannot open raw block devices. Device discovery, profile management, analysis, imaging, verification, restore, browsing, and other privileged work cross a local Unix-domain socket as narrow commands.

This boundary limits the consequence of an interface bug. A malformed button state cannot become raw-device authority unless the service independently validates the request, device identity, bench role, and operation preconditions.

Runtime layers

ArcoBASIC communication layer: task presentation, operator input, policy, and factual status
Local IPC protocol: bounded requests, responses, job identifiers, and progress events
lazarus-service: authoritative policy enforcement and active-device state
Recovery mechanisms: discovery, inspection, imaging, verification, restore, and format logic
Linux and Lazarus OS: raw block permissions, mounts, udev policy, and process isolation

Long operations remain observable

Imaging, verification, and restore emit structured progress records with operation, phase, factual message, byte counters, chunk counters, and an indeterminate flag where no useful total exists. The interface consumes state instead of scraping terminal prose.

The service accepts independent clients concurrently, allowing status and hotplug queries to remain responsive while a disk operation continues.

An ArcoBASIC communication boundary

ArcoBASIC exposes progress and permitted operations as understandable ideas without granting arbitrary raw-device access. The sample translates structured events into calm operator language while keeping policy visible in source.

ArcoBASICArcoBASIC communication example: render factual service progress

' Convert a structured service event into an operator-facing status.
FUNCTION DescribeProgress(event)
    ' Flush and finalization still involve active storage writes.
    IF event.Phase == "flush" OR event.Phase == "finalize" THEN
        RETURN "FLUSHING: DO NOT DISCONNECT"
    END IF

    IF event.Phase == "failed" THEN
        RETURN "STOPPED: " + event.Message
    END IF

    ' Some phases have no honest percentage yet.
    IF event.Indeterminate THEN RETURN event.Message

    IF event.TotalBytes <= 0 THEN RETURN event.Message
    percent = (event.CompletedBytes * 100) / event.TotalBytes
    RETURN event.Message + " (" + percent + "%)"
END FUNCTION

event = {
    "Phase": "verify",
    "Message": "Reopening and hashing stored chunks",
    "Indeterminate": FALSE,
    "CompletedBytes": 750,
    "TotalBytes": 1000
}

PRINT DescribeProgress(event)

Arco App Capsules remain constrained

An Arco App Capsule may contain Lazarus-facing ArcoBASIC, assets, documentation, and non-privileged libraries for metadata, verification, and browsing. It must not become the authority that opens arbitrary raw devices.

Operating-system policy continues to own device permissions, mount namespaces, destructive capabilities, and signed service deployment. Readable application code is valuable precisely because it sits on top of a smaller, defensible authority boundary.

A narrow boundary beats a clever interface

The Unix-domain socket between the GTK interface and lazarus-service is a detail specific to this appliance. The reason that boundary exists at all, and where it is drawn, is the part that applies well outside recovery software.

This is the same argument for a database sitting behind an API instead of being reachable directly from a browser, for a payment flow that never lets the client hold real card data, or for a plugin system that runs untrusted code in a sandbox instead of the host process. The safest interface is the one that structurally cannot do the dangerous thing, no matter how it is compromised.

Put the dangerous capability behind the smallest possible surface. The interface cannot open a raw block device under any circumstance; it can only ask a service that independently re-validates the request, so a UI bug caps out at a rejected command, not a corrupted disk.
Design the protocol around bounded, structured messages instead of an open channel. Progress crosses the socket as operation, phase, byte counters, and an explicit indeterminate flag, so DescribeProgress never has to guess or scrape output to know what happened.
Let the service stay authoritative even when several things are asking it questions at once. Status and hotplug queries stay responsive while an imaging job runs, because the boundary was drawn around the resource, not around a single session.
Keep the presentation layer honest about what it does not have permission to do. Arco App Capsules can hold non-privileged Lazarus-facing code, but the page is explicit that a capsule must never become the authority that opens arbitrary devices.

LEARNING LAYER

Key terms, in plain language

You do not need a systems background to follow the work. These are the specialized terms used on this page.

IPCInter-process communication: A controlled way for separate programs to exchange requests, responses, and events. Lazarus uses it to keep the interface separate from raw-device authority.
Unix-domain socket: A local communication channel that lets processes on the same machine exchange structured requests without exposing a network service.
Bench policy: Rules assigning physical recovery-bench ports and devices to roles such as source-only, destination-only, image storage, or ignored.