Xyn Terminology: Blueprints, Modules, Bundles, and the Plan-Always Control Plane

Xyn is designed as a platform builder for an AI-native world — not merely as a single application runtime. That distinction matters, because platform building requires a consistent vocabulary for:

• design-time intent (what we want to build)
• composition-time intent (how reusable components are selected and assembled)
• deployment-time intent (what should run)
• run-time orchestration (what is actually running)

This article defines the core terminology used across Xyn and presents diagrams showing how the system’s objects and processes connect. The aim is to provide a stable conceptual map for both development and operations, especially as Xyn evolves into a full control plane for long-running services.

---

Core design philosophy

Before exploring terminology, a few invariants clarify why these objects exist.

1) Declarative desired state

In Xyn, long-running services are represented as data. Desired outcomes (what should exist and how it should behave) must be expressible in a structured, machine-readable form.

2) Plan-always changes

Any meaningful change to infrastructure is expressed as:

Plan → Review → Apply → Observe

This workflow ensures change safety in both human-driven and AI-assisted environments. It prevents automation from bypassing review, and it enables auditability and repeatability.

3) Compile to run-time intent

Blueprints, Bundles, and ReleaseSpecs are not executed directly. Higher-level design-time and packaging-time objects are compiled into lower-level executable intent.

This is a core pattern in Xyn:

Humans author intent. The control plane compiles. The backend applies.

---

Core objects and terminology

SolutionBlueprintSpec (formerly BlueprintSpec)

A SolutionBlueprintSpec is a reusable, parameterized template that defines a full solution pattern. It captures design-time intent and is intended to be instantiated repeatedly across environments.

SolutionBlueprintSpecs describe:

• a solution’s conceptual components
• required parameters and defaults
• policy boundaries (optional)
• required capabilities
• how to select and compose modules
• what bundle(s) should be produced
• templates that produce ReleaseSpecs deterministically

Examples:

• “Monitoring stack”
• “Website + Postgres”
• “Runner stack”
• “EMS management platform (Mikrotik + PON device bundle)”
• “Network service controller”

Key shift: Solution blueprints describe outcomes and constraints, not implementation details. They are capability-driven.

---

ModuleSpec (Module)

A Module is the smallest independently versioned and releasable unit in Xyn.

A ModuleSpec describes one module and establishes the boundaries that enable reuse. Xyn treats modules as first-class concepts because they create stable decomposition surfaces for both humans and AI coding agents.

Modules are intended to be reusable across solutions. A solution blueprint should mostly be composition glue.

A ModuleSpec includes:

• identity + namespace (FQN)
• type (adapter, service, ui, workflow, schema, infra, lib)
• capabilities provided
• interface contracts (OpenAPI/AsyncAPI/schema refs)
• dependencies (other modules or capabilities)
• owned data surfaces (tables/schemas)
• quality gates (tests/security)

Examples:

• xyence.adapter.mikrotik-ztp
• xyence.adapter.omci-voltha
• xyence.ui.ems-console
• xyn.core.secrets
• xyence.infra.tenant-isolation-aws-dedicated

---

Capability Contract

A Capability is a named intent contract the platform can require, and a module can provide.

Capabilities exist so blueprints do not hard-bind to specific implementations.

Examples:

• DeviceBootstrap (e.g., Mikrotik DHCP option 43 → ZTP)
• FirmwareManagement (RouterOS firmware orchestration)
• AccessDeviceManagement (e.g., PONCAN control plane API)
• OMCIOrchestration (e.g., VOLTHA-backed flows)
• TenantIsolation (AWS dedicated VPC + dedicated cluster)

Capabilities are versioned independently and can include a profile, such as:

• mikrotik-routeros
• poncan
• voltha

---

BundleSpec (Bundle)

A BundleSpec is a packaging-time object: a description of a deployable unit produced by composing specific versions of modules.

BundleSpecs answer:

• which modules are included?
• what versions?
• what configuration surfaces exist?
• where is it deployable?
• what compatibility rules exist (e.g., required Xyn version)?

Examples:

• xyence.bundle.antronix-ems
• xyence.bundle.website-stack

Important clarification:
Bundle (platform) is a deployable package.
A domain “bundle” (e.g., Mikrotik + PON device tracked as one product entity) is separate and should be modeled explicitly in the solution’s domain schema.

---

BlueprintInstance

A BlueprintInstance represents one concrete realization of a SolutionBlueprintSpec. It binds:

• blueprint revision
• parameter values
• environment bindings

BlueprintInstances are the bridge between reusability and specificity:

• SolutionBlueprintSpec: reusable solution intent
• BlueprintInstance: solution deployed into a particular environment

---

ReleaseSpec

A ReleaseSpec is the canonical expression of deployment-time intent. It describes a single deployable release: service(s), configuration, ports, storage, and versions that should exist.

ReleaseSpecs answer:

• what components should exist?
• what images/build artifacts?
• what exposure rules?
• what volumes?
• which backend is targeted? (Docker Compose today, Kubernetes later)

In Xyn, ReleaseSpec is the stable unit of long-running lifecycle management.

---

RuntimeSpec

A RuntimeSpec is a compiled representation of the release optimized for orchestration.

In Xyn:

• ReleaseSpec is optimized for authoring
• RuntimeSpec is optimized for execution

RuntimeSpecs are deterministic and backend-aligned. They are suitable for being rendered into:

• compose.yaml
• Kubernetes manifests (future)

---

ReleasePlan

A ReleasePlan is a deterministic change description produced before any mutation occurs. It exists to enforce plan-always workflows and to enable review.

ReleasePlans include:

• actions (create/update/delete/noop)
• artifacts (compiled specs, backend render outputs, diffs)
• references to release revision metadata

ReleasePlans are also reused for module and bundle delivery, not only runtime releases. In other words:

• ReleasePlan → Module v0.1.0 (deliverable)
• ReleasePlan → Bundle v0.1.0 (deliverable)
• ReleasePlan → Release runtime change (deployable)

---

Operation

An Operation is a durable record of execution. It captures what happened when a plan was applied (or when reconciliation acted on drift).

Operations track:

• status (queued/running/succeeded/failed)
• timestamps
• logs
• output artifacts
• references to the associated plan + revision

---

ReleaseStatus

A ReleaseStatus describes the current observed state for a release.

It typically includes:

• desired revision
• observed revision
• per-service state and health
• top-level summary: running / stopped / degraded

ReleaseStatus is the foundation for reconciliation loops.

---

xyn-seed: the control plane

Xyn’s control plane responsibilities are implemented in xyn-seed.

xyn-seed:

• validates inputs against xyn-contracts
• resolves required capabilities → module selections (via Module Registry)
• assembles BundleSpecs
• compiles ReleaseSpec → RuntimeSpec
• generates ReleasePlans
• applies plans through backends
• performs drift reconciliation
• maintains Operations and Status

---

Diagram 1 — Full object lifecycle (solution → modules → bundle → runtime)

 

flowchart TD
    A["SolutionBlueprintSpec<br/>(Design-time solution intent)"] --> B["BlueprintInstance<br/>(Parameters + environment)"]

    B --> C["Capability Requirements<br/>(profiles + constraints)"]
    C --> D["Module Resolution<br/>(Module Registry search/scoring)"]
    D --> E["ModuleSpecs<br/>(Reusable components)"]

    E --> F["BundleSpec<br/>(Deployable package)"]
    F --> G["ReleaseSpec<br/>(Deploy-time intent)"]
    G --> H["RuntimeSpec<br/>(Compiled run-time intent)"]
    H --> I["Backend Render<br/>compose.yaml / k8s manifests"]
    I --> J["Apply<br/>Compose / K8s"]
    J --> K["ReleaseStatus<br/>Observed state"]

    G --> L["ReleasePlan<br/>Actions + artifacts"]
    L --> M["Operation<br/>Execution record"]
    M --> K

    subgraph xyn_contracts["xyn-contracts"]
      A
      E
      F
      G
      H
      L
      M
      K
    end

    subgraph xyn_seed["xyn-seed"]
      D
      F
      H
      L
      M
      K
    end

---

Diagram 2 — Control plane responsibilities (API-first architecture)

This diagram separates the authoring UI from the deployment authority, reducing risk while still enabling fast iteration and AI-assisted workflows.

 

flowchart LR
    UI["xyence-web<br/>Django Admin + AI Studio"]
    BA["Blueprint Studio<br/>(Solution/Module/Bundle authoring)"]
    CP["xyn-seed<br/>Control Plane API"]
    CT["xyn-contracts<br/>Schemas + OpenAPI"]

    MR["Module Registry"]
    CC["Capability Catalog"]
    AS["Bundle Assembler"]

    RT["Runtime Compiler"]
    PL["Planner"]
    BE["Backend Adapter"]
    RC["Reconciler"]

    DOCKER["Docker Compose Backend"]
    K8S["Kubernetes Backend"]
    OBS["Observed Containers/Services"]

    UI -->|Plan/Apply requests| CP
    UI -->|Author/manage| BA
    BA --> UI

    CP -->|Validate| CT

    CP --> MR
    CP --> CC
    CP --> AS

    CP -->|Compile| RT
    CP -->|Plan| PL
    CP -->|Apply| BE
    CP -->|Status/Reconcile| RC

    BE -->|compose.yaml| DOCKER
    BE -.->|future| K8S

    DOCKER --> OBS
    OBS -->|Inspect| CP

    subgraph solution_mgmt["Solution + Module + Bundle Management"]
      UI
      BA
      MR
      CC
      AS
    end

---

Diagram 3 — Release management: plan/apply/status in practice

 

sequenceDiagram
    autonumber
    participant User
    participant Studio as AI Studio (xyence-web)
    participant Seed as xyn-seed API
    participant Registry as Module Registry
    participant Assembler as Bundle Assembler
    participant Backend as Compose Backend
    participant Ops as Operation Store
    participant Status as Status/Reconciler

    User->>Studio: Submit SolutionBlueprintSpec + params
    Studio->>Seed: POST /solutions/plan (BlueprintInstance)
    Seed->>Registry: resolve capabilities to modules
    Registry-->>Seed: selected module versions
    Seed->>Assembler: assemble BundleSpec
    Assembler-->>Seed: BundleSpec

    Seed->>Seed: validate + compile + diff
    Seed-->>Studio: ReleasePlan (actions + artifacts)
    Studio-->>User: Show plan diff

    User->>Studio: Apply plan
    Studio->>Seed: POST /plans/{id}/apply
    Seed->>Ops: create Operation (running)
    Seed->>Backend: docker compose up -d
    Backend-->>Seed: results
    Seed->>Ops: mark Operation succeeded

    loop periodic
        Status->>Backend: inspect compose project
        Backend-->>Status: container states + health
        Status-->>Seed: update ReleaseStatus
    end

    Studio->>Seed: GET /releases/{id}/status
    Seed-->>Studio: ReleaseStatus
    Studio-->>User: running/degraded/stopped

---

Why this vocabulary matters (especially with AI involved)

A control plane must be strict about object boundaries and change workflows. In Xyn, terminology isn’t just documentation — it is part of the safety architecture.

A model or automation system can generate:

• a ModuleSpec
• a SolutionBlueprintSpec
• a BlueprintInstance
• a BundleSpec
• a ReleaseSpec

But:

• xyn-seed validates against contracts
• a plan is generated and reviewed
• only then is apply allowed
• status + reconciliation keep reality aligned with intent

This structure allows AI to accelerate development without turning infrastructure into an opaque prompt-driven system.

---

Glossary (quick reference)

• SolutionBlueprintSpec — reusable solution intent (design-time)
• ModuleSpec — reusable module contract (component-level)
• Capability Contract — named intent requirement/provision contract
• BundleSpec — deployable composition of module versions
• BlueprintInstance — parameterized solution instance (environment-scoped)
• ReleaseSpec — concrete deployable intent (deploy-time)
• RuntimeSpec — compiled runtime representation (run-time)
• ReleasePlan — planned change set + artifacts (pre-mutation safety)
• Operation — execution record (apply/reconcile)
• ReleaseStatus — observed state + health
• xyn-seed — control plane (resolve/assemble/compile/plan/apply/status/reconcile)
• xyence-web — authoring UI + AI Studio operator surface
• xyn-contracts — schemas + OpenAPI (shared truth across components)

---

What comes next

This terminology provides the foundation for deeper topics that follow naturally:

• designing capability contracts and profiles
• deterministic composition (module resolution + bundle assembly)
• module compatibility matrices
• drift correction and reconciliation strategies
• blueprint parameter schema design
• safe tool execution planes and controlled primitives