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