Status: working draft — summarizes stable structural decisions plus evolving architecture; specifics marked evolving may change before the next baseline.

Architecture

Shape of the system

Xtrape is realized through an authoritative shared control plane — the Platform — with interaction products around it and governed Services connected to it.

   users / AI clients / channels
        |          |         |
      Panel    Exposure   Telegram        (Interaction Layer)
        \          |         /
         \         |        /
          Xtrape Platform                 (registry · policy · credential ·
           |       |       |               message · audit/trace · lifecycle)
        Service Service Service           (each: Capabilities → Actions,
           |       |       |               published Checkpoints)
         Worker  Worker  Worker           (execution units; one Service may
                                           have many, sharing one token)

Key structural commitments:

• Interaction products hold no authority. The operator panel, the AI-facing exposure surface, and chat adapters own no independent registry, policy, credential, deployment authorization, or audit state. They are clients of Platform foundations.
• The Platform holds logical authority over admission, registry, resolution, authorization, invocation coordination, and audit — without prescribing process count, clustering, or deployment topology (open decisions).
• Services own their business. A Service's own business configuration is managed through the Service's entry actions; the Platform routes and audits execution but does not become the owner of service-internal state.
• Platform modules in the Community Edition baseline: registry, configuration, message, policy, credential, audit/trace, plus lifecycle and handoff validation.

Current topology (Community Edition)

The shipped 0.7.x baseline is single-tenant and single-node, with SQLite by default, and the connected runtime initiating transport toward the Platform (long-poll; no inbound connectivity required at the service side). High availability, multi-node guarantees, multi-tenancy, and platform-initiated transport are explicitly outside the current boundary.

Authoring vs operating

Authoring and operations are separated by output, not by privilege escalation:

• authoring surfaces (Studio for server-side authoring, Workbench as the local-first desktop workbench — both design-stage) produce a Widget candidate plus handoff evidence;
• the Platform validates the candidate and issues an authorized install plan;
• launcher/deployment machinery executes it;
• the result is a live, registered Service with its Workers — the deployment brings up a Worker, the Worker registers, and the first completed registration is what makes the Platform create the Service.

Neither the authoring surface nor the operator UI holds deployment authority. Early Studio scenarios are deliberately restricted to zero-governed-approval operations (read-only analysis, allow-listed outputs); write paths arrive later in the release train.

Multi-platform future

Collaboration between platforms is modeled as Platform-to-Platform capability exposure — one Platform registering selected exposed Checkpoints with another — not as gateway federation. This is a direction-setting draft, not an enforced baseline.

For the authorization, audit, and evidence model, see Controlled Execution.