ignition-stack 0.4.0__tar.gz → 0.6.0__tar.gz

{ignition_stack-0.4.0 → ignition_stack-0.6.0}/.gitignore

@@ -30,3 +30,6 @@ Thumbs.db
 .env
 .env.local
 *.env
+
+# Tool artifacts
+.playwright-mcp/

{ignition_stack-0.4.0 → ignition_stack-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ignition-stack
-Version: 0.4.0
+Version: 0.6.0
 Summary: CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements
 Author-email: Eric Knorr <etknorr@gmail.com>
 License: MIT
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 [![Docs](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml)
 [![Documentation](https://img.shields.io/badge/docs-ia--eknorr.github.io-blue)](https://ia-eknorr.github.io/ignition-stack/)
 
-CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Picks an architecture profile, asks a few questions, writes a self-contained project with a hand-readable compose file, env, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
+CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Pick a system architecture (`basic`, `scale-out`, or `hub-and-spoke`), layer on services, and it writes a self-contained project: a hand-readable compose file, `.env`, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
 
 See [`docs/docs/reference/seeding-matrix.md`](docs/docs/reference/seeding-matrix.md) for which Ignition 8.3 connection types can be provisioned from the filesystem and env on a live 8.3.6 gateway. Full documentation lives in the [`docs/`](docs/) Docusaurus site.
 
@@ -55,23 +55,25 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo
+ignition-stack init demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
+Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from a profile and a few prompts. |
+| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
 | `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-profile` | Reshape an SE-demo project under a different profile. |
+| `switch-arch` | Reshape an SE-demo project under a different architecture. |
 | `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.

{ignition_stack-0.4.0 → ignition_stack-0.6.0}/README.md

@@ -4,7 +4,7 @@
 [![Docs](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml/badge.svg)](https://github.com/ia-eknorr/ignition-stack/actions/workflows/docs.yml)
 [![Documentation](https://img.shields.io/badge/docs-ia--eknorr.github.io-blue)](https://ia-eknorr.github.io/ignition-stack/)
 
-CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Picks an architecture profile, asks a few questions, writes a self-contained project with a hand-readable compose file, env, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
+CLI that generates ready-to-run Docker Compose stacks for Ignition 8.3 SCADA demos and SE engagements. Pick a system architecture (`basic`, `scale-out`, or `hub-and-spoke`), layer on services, and it writes a self-contained project: a hand-readable compose file, `.env`, file-config seed resources, and a `POST-SETUP.md` listing only what could not be pre-seeded.
 
 See [`docs/docs/reference/seeding-matrix.md`](docs/docs/reference/seeding-matrix.md) for which Ignition 8.3 connection types can be provisioned from the filesystem and env on a live 8.3.6 gateway. Full documentation lives in the [`docs/`](docs/) Docusaurus site.
 
@@ -26,23 +26,25 @@ pipx install git+https://github.com/ia-eknorr/ignition-stack.git@<branch>
 Generate a project and bring it up:
 
 ```sh
-ignition-stack init demo
+ignition-stack init demo --arch basic
 cd demo
 docker compose up -d
 ```
 
 The gateway reaches RUNNING with no UI prompts. The admin user is `admin / password` and the gateway is at `http://localhost:9088`. The default Postgres credentials are `ignition / ignition` on the `db` service.
 
+Run `init` without `--arch` to walk the interactive wizard instead: it opens architecture-first, then layers database, edition, IIoT, services, and exposure on top, with a summary you can preview, tweak, or generate.
+
 Everything that ships in the generated project is hand-readable: `docker-compose.yaml`, `.env`, `scripts/docker-bootstrap.sh`, and a `services/ignition/` resources tree the gateway reads on first boot.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init <name>` | Generate a project at `./<name>/` from a profile and a few prompts. |
+| `init <name>` | Generate a project at `./<name>/` from an architecture and a few prompts. |
 | `modules` | Download, verify, and manage the `.modl` / JDBC catalog. |
 | `reset` | Re-run generation from an SE-demo project's recorded config. |
-| `switch-profile` | Reshape an SE-demo project under a different profile. |
+| `switch-arch` | Reshape an SE-demo project under a different architecture. |
 | `wipe` | Remove this project's containers and volumes only. |
 
 See the [CLI reference](docs/docs/reference/cli.md) for every command, argument, and option.

{ignition_stack-0.4.0 → ignition_stack-0.6.0}/builtin_modules.yaml

@@ -25,6 +25,15 @@
 # `identifier` is the fully-qualified module id used verbatim in
 # GATEWAY_MODULES_ENABLED. `slug` is the friendly kebab name a user puts in
 # `disable_builtins`. `name` is the gateway's display name (for wizard labels).
+#
+# `default_enabled` marks the curated "typical demo" set the interactive wizard
+# pre-checks (opt-in selection). It does NOT change the engine math or the
+# non-interactive profile path - profiles still enable every built-in. It only
+# seeds the wizard's checkbox so the common path is a lean gateway. The JDBC
+# drivers are all `default_enabled: false` on purpose: the wizard enables the
+# one matching the chosen database (see `jdbc_driver_for`), not a static one.
+# The smoke guard checks the module *set*, not this curation flag, so the
+# default-set invariants live in tests/test_disable_builtins.py instead.
 
 version: 1
 
@@ -36,87 +45,116 @@ modules:
   - slug: alarm-notification
     identifier: com.inductiveautomation.alarm-notification
     name: Alarm Notification
+    default_enabled: true
   - slug: allen-bradley-driver
     identifier: com.inductiveautomation.opcua.drivers.ablegacy
     name: Allen-Bradley Driver
+    default_enabled: false
   - slug: bacnet-driver
     identifier: com.inductiveautomation.opcua.drivers.bacnet
     name: BACnet Driver
+    default_enabled: false
   - slug: enterprise-administration
     identifier: com.inductiveautomation.eam
     name: Enterprise Administration
+    default_enabled: false
   - slug: event-streams
     identifier: com.inductiveautomation.eventstream
     name: Event Streams
+    default_enabled: false
   - slug: historian-core
     identifier: com.inductiveautomation.historian
     name: Historian Core
+    default_enabled: true
   - slug: kafka-connector
     identifier: com.inductiveautomation.connectors.kafka
     name: Kafka Connector
+    default_enabled: false
   - slug: legacy-dnp3-driver
     identifier: com.inductiveautomation.opcua.drivers.dnp3
     name: Legacy DNP3 Driver
+    default_enabled: false
   - slug: logix-driver
     identifier: com.inductiveautomation.opcua.drivers.logix
     name: Logix Driver
+    default_enabled: false
   - slug: mariadb-jdbc-driver
     identifier: com.inductiveautomation.jdbc.mariadb
     name: MariaDB JDBC Driver
+    default_enabled: false
   - slug: micro800-driver
     identifier: com.inductiveautomation.opcua.drivers.micro800
     name: Micro800 Driver
+    default_enabled: false
   - slug: mitsubishi-driver
     identifier: com.inductiveautomation.opcua.drivers.mitsubishi
     name: Mitsubishi Driver
+    default_enabled: false
   - slug: modbus-driver
     identifier: com.inductiveautomation.opcua.drivers.modbus
     name: Modbus Driver
+    default_enabled: false
   - slug: mssql-jdbc-driver
     identifier: com.inductiveautomation.jdbc.mssql
     name: MSSQL JDBC Driver
+    default_enabled: false
   - slug: omron-driver
     identifier: com.inductiveautomation.opcua.drivers.omron
     name: Omron Driver
+    default_enabled: false
   - slug: opc-ua
     identifier: com.inductiveautomation.opcua
     name: OPC-UA
+    default_enabled: true
   - slug: perspective
     identifier: com.inductiveautomation.perspective
     name: Perspective
+    default_enabled: true
   - slug: postgresql-jdbc-driver
     identifier: com.inductiveautomation.jdbc.postgresql
     name: PostgreSQL JDBC Driver
+    default_enabled: false
   - slug: reporting
     identifier: com.inductiveautomation.reporting
     name: Reporting
+    default_enabled: true
   - slug: sfc
     identifier: com.inductiveautomation.sfc
     name: SFC
+    default_enabled: false
   - slug: siemens-drivers
     identifier: com.inductiveautomation.opcua.drivers.siemens
     name: Siemens Drivers
+    default_enabled: false
   - slug: siemens-enhanced-driver
     identifier: com.inductiveautomation.opcua.drivers.siemens-symbolic
     name: Siemens Enhanced Driver
+    default_enabled: false
   - slug: sms-notification
     identifier: com.inductiveautomation.sms-notification
     name: SMS Notification
+    default_enabled: false
   - slug: sql-bridge
     identifier: com.inductiveautomation.sqlbridge
     name: SQL Bridge
+    default_enabled: true
   - slug: sql-historian
     identifier: com.inductiveautomation.historian.sql
     name: SQL Historian
+    default_enabled: true
   - slug: symbol-factory
     identifier: com.inductiveautomation.symbol-factory
     name: Symbol Factory
+    default_enabled: false
   - slug: udp-and-tcp-drivers
     identifier: com.inductiveautomation.opcua.drivers.tcpudp
     name: UDP and TCP Drivers
+    default_enabled: false
   - slug: vision
     identifier: com.inductiveautomation.vision
     name: Vision
+    default_enabled: false
   - slug: webdev
     identifier: com.inductiveautomation.webdev
     name: WebDev
+    default_enabled: false

ignition_stack-0.6.0/ignition_stack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

ignition_stack-0.6.0/ignition_stack/architectures/__init__.py

@@ -0,0 +1,35 @@
+"""System architectures: pre-canned shapes that turn intent into config.
+
+The slugs mirror Ignition's documented system architectures (Basic / Scale Out
+/ Hub and Spoke). Importing this package registers every built-in architecture
+by side-effect so ``get_architecture("scale-out")`` works without explicit
+module imports.
+"""
+
+from ignition_stack.architectures import basic, hub_and_spoke, scale_out  # noqa: F401
+from ignition_stack.architectures.advisory import Advisory, spoke_advisory
+from ignition_stack.architectures.base import (
+    Architecture,
+    ArchOptions,
+    apply_iiot,
+    build_architecture,
+    can_host_redundant_role,
+    get_architecture,
+    list_architectures,
+    mark_redundant,
+)
+from ignition_stack.architectures.hub_and_spoke import ArchitectureError
+
+__all__ = [
+    "Advisory",
+    "ArchOptions",
+    "Architecture",
+    "ArchitectureError",
+    "apply_iiot",
+    "build_architecture",
+    "can_host_redundant_role",
+    "get_architecture",
+    "list_architectures",
+    "mark_redundant",
+    "spoke_advisory",
+]

{ignition_stack-0.4.0/ignition_stack/profiles → ignition_stack-0.6.0/ignition_stack/architectures}/advisory.py

@@ -1,6 +1,6 @@
 """Hub-and-spoke RAM advisory.
 
-The hub-and-spoke profile spins up one hub gateway plus *N* spokes; each
+The hub-and-spoke architecture spins up one hub gateway plus *N* spokes; each
 Ignition gateway needs ~1.5 GB to run comfortably. The advisory turns that
 math into a proportional friction signal so SEs can see the cost of a
 large demo without being silently blocked when they really do want it:

ignition_stack-0.6.0/ignition_stack/architectures/base.py

@@ -0,0 +1,344 @@
+"""Architecture contract + options + registry.
+
+An *architecture* is the small piece of code that turns the user's high-level
+intent ("scale-out", "hub-and-spoke with 3 spokes") into a fully-formed
+:class:`ProjectConfig`. The slugs mirror Ignition's own documented system
+architectures (Basic / Scale Out / Hub and Spoke). The compose engine and the
+dependency resolver are architecture-agnostic; architectures only shape the
+inputs they take.
+
+Two-stage pipeline:
+
+1. Either the CLI flags or the wizard answers populate an
+   :class:`ArchOptions` and pick an architecture slug.
+2. ``build_architecture(slug, name, options)`` looks up the architecture and
+   calls its ``build()`` method, returning a ``ProjectConfig`` that
+   ``services.resolver.resolve()`` then expands the usual implicit deps on.
+
+Each architecture is a small dataclass with three pieces:
+
+- ``slug`` - the wizard/flag value users type.
+- ``summary`` - one-line description for the wizard menu + docs.
+- ``build`` - pure function ``(name, options) -> ProjectConfig``.
+
+Keeping ``build`` pure (no I/O, no prompts) is what lets the wizard layer
+and the CLI flag layer share the same code path and stay testable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from ignition_stack.config import (
+    GatewayConfig,
+    ProjectConfig,
+    RedundancyConfig,
+    ReverseProxyConfig,
+    ServiceAttachment,
+    ServiceInstance,
+)
+
+
+@dataclass(frozen=True)
+class ArchOptions:
+    """Inputs each architecture reads to shape the resolved config.
+
+    Every field has a sensible default so callers only set what they
+    actually care about. The wizard fills in many of these from prompts;
+    the non-interactive CLI path fills in a subset from flags and leaves
+    the rest at their defaults.
+    """
+
+    spokes: int = 3
+    """Hub-and-spoke spoke count. Ignored by other architectures."""
+
+    frontends: int = 1
+    """Scale-out frontend gateway count. Ignored by other architectures.
+
+    1 yields a single gateway named ``frontend``; N>1 yields
+    ``frontend-1``..``frontend-N``. A ``backend`` gateway is always added
+    on top.
+    """
+
+    force: bool = False
+    """Bypass the hub-and-spoke red-tier advisory. Ignored elsewhere."""
+
+    network_split: bool | None = None
+    """Tri-state override for the frontend/backend network split.
+
+    ``None`` lets each architecture apply its own default (scale-out splits,
+    hub-and-spoke does not). ``True``/``False`` force the split on or off
+    regardless of the architecture default.
+    """
+
+    edge_role: str | None = None
+    """Which gateway role (if any) runs the Edge edition.
+
+    For scale-out this is typically 'frontend'; for hub-and-spoke it can
+    be 'spoke' (every spoke runs Edge) or None. The architecture is free to
+    apply its own default when this is None.
+    """
+
+    reverse_proxy: ReverseProxyConfig | None = None
+    """Reverse-proxy scaffolding. None = plain host-port mapping."""
+
+    database_kind: str | None = "postgres"
+    """SQL database for the stack. None = no database (gateway-only)."""
+
+    services: tuple[str, ...] = ()
+    """Additional service catalog slugs the user picked beyond architecture defaults."""
+
+    redundant_role: str | None = None
+    """Role (or gateway name) to make redundant, expanding it into a master +
+    backup pair. ``None`` (default) builds no redundancy. Must name a singleton
+    workhorse role (scale-out 'backend', hub-and-spoke 'hub', basic
+    'gateway'); replicated tiers ('frontend', 'spoke') are rejected."""
+
+    disable_builtins: tuple[str, ...] = ()
+    """Built-in module slugs to turn off on every gateway in the stack.
+
+    Empty (default) leaves all built-ins on. Applied uniformly by
+    ``build_architecture`` - the demo intent is "drop Vision/SFC everywhere",
+    and per-gateway disabling stays a declarative-config-only feature. Slugs
+    are validated against builtin_modules.yaml by ``GatewayConfig``."""
+
+    iiot: bool = False
+    """Overlay an MQTT/Sparkplug IIoT pipeline (a broker + Cirrus Link
+    Transmission/Engine) onto the stack. Off by default; ``build_architecture``
+    calls :func:`apply_iiot` when this is set, defaulting the broker to
+    ``chariot``."""
+
+    iiot_broker: str | None = None
+    """MQTT broker slug the IIoT overlay wires to. ``None`` with ``iiot`` on
+    means the confirmed default ``chariot`` (Cirrus Link's own broker). Ignored
+    when ``iiot`` is False. Validated against the catalog by :func:`apply_iiot`."""
+
+
+class Architecture(Protocol):
+    """A factory that turns ``ArchOptions`` into a ``ProjectConfig``."""
+
+    slug: str
+    summary: str
+
+    def build(self, name: str, options: ArchOptions) -> ProjectConfig: ...
+
+
+# Registry populated by the architecture modules at import time. Keep
+# alphabetical insertion-order for stable wizard menus + --help listings.
+_REGISTRY: dict[str, Architecture] = {}
+
+
+def register(architecture: Architecture) -> Architecture:
+    """Register an architecture by slug. Returns the architecture so module-level
+    uses can write ``basic = register(BasicArchitecture())``.
+    """
+    if architecture.slug in _REGISTRY:
+        raise ValueError(f"architecture '{architecture.slug}' is already registered")
+    _REGISTRY[architecture.slug] = architecture
+    return architecture
+
+
+def get_architecture(slug: str) -> Architecture:
+    """Look up a registered architecture by slug. Raises ``KeyError`` if unknown."""
+    try:
+        return _REGISTRY[slug]
+    except KeyError as exc:
+        known = ", ".join(sorted(_REGISTRY))
+        raise KeyError(f"unknown architecture '{slug}'; known architectures: {known}") from exc
+
+
+def list_architectures() -> list[Architecture]:
+    """All registered architectures in stable insertion order."""
+    return list(_REGISTRY.values())
+
+
+# Roles that are horizontally replicated, not paired. Ignition redundancy is a
+# two-node master/backup arrangement, so a tier that can have many members
+# (frontends, spokes) is never the redundancy target - those scale out, they
+# don't fail over. Marking one redundant is a usage error.
+_NON_REDUNDANT_ROLES = frozenset({"frontend", "spoke"})
+
+
+def _matching_gateways(config: ProjectConfig, redundant_role: str) -> list:
+    """Gateways a redundant role names, matched by role or name.
+
+    The single matching rule shared by :func:`mark_redundant` (which errors on a
+    bad match) and :func:`can_host_redundant_role` (which only reports), so the
+    two can never drift on what "matches" means.
+    """
+    return [gw for gw in config.gateways if redundant_role in (gw.role, gw.name)]
+
+
+def can_host_redundant_role(config: ProjectConfig, redundant_role: str) -> bool:
+    """True when ``config`` has exactly one gateway that can be paired as master.
+
+    ``switch-arch`` uses this to decide whether redundancy intent recovered from
+    the old stack can carry to the target architecture, without raising the way
+    :func:`mark_redundant` does - an architecture-specific role (e.g. basic's
+    ``gateway``) simply may not exist in the destination.
+    """
+    if redundant_role in _NON_REDUNDANT_ROLES:
+        return False
+    return len(_matching_gateways(config, redundant_role)) == 1
+
+
+def mark_redundant(config: ProjectConfig, redundant_role: str | None) -> ProjectConfig:
+    """Stamp the gateway named/roled ``redundant_role`` as a redundancy master.
+
+    Returns ``config`` unchanged when ``redundant_role`` is None. The expansion
+    into a master+backup pair happens later in
+    :func:`ignition_stack.services.resolver.resolve`; this only marks which
+    gateway to pair, so the same logic serves every architecture and the wizard.
+
+    Raises ``ValueError`` (surfaced by the CLI as a usage error, exit code 2)
+    when the role is a replicated frontend/spoke tier, unknown, or ambiguous
+    (matches more than one gateway - you can't pair a horizontally-scaled tier).
+    """
+    if redundant_role is None:
+        return config
+    if redundant_role in _NON_REDUNDANT_ROLES:
+        raise ValueError(
+            f"role '{redundant_role}' is horizontally replicated, not paired; "
+            "redundancy applies to a single gateway (e.g. a scale-out 'backend' "
+            "or a hub-and-spoke 'hub'), never to frontends or spokes"
+        )
+    matches = _matching_gateways(config, redundant_role)
+    if not matches:
+        known = ", ".join(sorted({gw.role or gw.name for gw in config.gateways}))
+        raise ValueError(f"no gateway matches redundant role '{redundant_role}'; available roles: {known}")
+    if len(matches) > 1:
+        raise ValueError(f"redundant role '{redundant_role}' matches {len(matches)} gateways; " "redundancy pairs a single gateway, so name a singleton role")
+    master = matches[0]
+    master.redundancy = RedundancyConfig(mode="master", peer=f"{master.name}-backup")
+    return config
+
+
+def build_architecture(slug: str, name: str, options: ArchOptions) -> ProjectConfig:
+    """Materialize a ``ProjectConfig`` for the named architecture.
+
+    The architecture builds the base topology; ``mark_redundant`` then stamps
+    the redundancy master when ``options.redundant_role`` is set, leaving the
+    resolver to expand the pair. Keeping the stamp here (not in each
+    architecture) means one eligibility rule serves every architecture and the
+    wizard alike.
+    """
+    config = get_architecture(slug).build(name, options)
+    config = mark_redundant(config, options.redundant_role)
+    config = apply_disable_builtins(config, options.disable_builtins)
+    broker = (options.iiot_broker or _IIOT_DEFAULT_BROKER) if options.iiot else None
+    return apply_iiot(config, broker)
+
+
+def apply_disable_builtins(config: ProjectConfig, disable_builtins: tuple[str, ...]) -> ProjectConfig:
+    """Stamp ``disable_builtins`` onto every gateway in ``config``.
+
+    Applied centrally (like :func:`mark_redundant`) so one rule serves every
+    architecture and the wizard. Uniform across gateways: the demo intent is to
+    drop a module everywhere, and a redundant pair must agree on its module set.
+    The resolver later copies the list onto any expanded backup node.
+    """
+    if not disable_builtins:
+        return config
+    # pydantic does not re-validate on attribute assignment, so validate here -
+    # this is the wizard/CLI choke point (the declarative path is checked at
+    # construction). Raises ValueError on an unknown slug; the CLI maps that to
+    # exit code 2.
+    from ignition_stack.catalog.builtins import validate_disable_slugs
+
+    validate_disable_slugs(list(disable_builtins))
+    for gw in config.gateways:
+        gw.disable_builtins = list(disable_builtins)
+    return config
+
+
+# The confirmed default IIoT broker (Cirrus Link's own Chariot, the most
+# official pairing with their Transmission/Engine modules). Used when the
+# overlay is requested without an explicit broker slug.
+_IIOT_DEFAULT_BROKER = "chariot"
+
+# Gateway roles that run MQTT Transmission (edge-side: publish Sparkplug to the
+# broker) versus MQTT Engine (central: subscribe and aggregate). A basic shape
+# has neither role, so its single gateway runs both for a self-contained demo
+# loop through the broker.
+_TRANSMISSION_ROLES = frozenset({"spoke", "frontend"})
+_ENGINE_ROLES = frozenset({"hub", "backend"})
+
+
+def apply_iiot(config: ProjectConfig, broker: str | None) -> ProjectConfig:
+    """Overlay an MQTT/Sparkplug IIoT pipeline onto ``config``.
+
+    Returns ``config`` unchanged when ``broker`` is None. Otherwise it adds the
+    broker as a stack-level :class:`ServiceInstance` (singleton, enforced by the
+    resolver) and wires each gateway by role, using the **module slugs the broker
+    manifest's ``wires.mqtt`` block names** (never hardcoded):
+
+    - ``spoke`` / ``frontend`` gateways get an ``mqtt-transmission`` attachment
+      plus the Transmission module (they publish Sparkplug to the broker);
+    - ``hub`` / ``backend`` gateways get an ``mqtt-engine`` attachment plus the
+      Engine module (they subscribe and aggregate);
+    - if NO gateway carries any of those roles (a basic shape), the single/first
+      gateway gets BOTH attachments + both modules - a self-contained demo loop
+      through the broker.
+
+    Brokers are not ``never_on_edge``, so an Edge spoke attaching with role
+    ``mqtt-transmission`` is correct and expected. Idempotent: guards on
+    ``(instance, role)`` attachment pairs and on module-already-present, so
+    ``apply_iiot(apply_iiot(c)) == apply_iiot(c)``. The expansion of a redundancy
+    master happens later in :func:`~ignition_stack.services.resolver.resolve`,
+    which copies the master's attachments + modules onto the backup, so a
+    redundant Engine gateway ends up with the Engine module on both nodes.
+
+    Raises ``ValueError`` (surfaced by the CLI as exit code 2) when the broker
+    slug is unknown, is not an ``mqtt-broker``, or carries no ``wires.mqtt`` block.
+    """
+    if broker is None:
+        return config
+
+    from ignition_stack.services.loader import load_all_services
+
+    catalog = load_all_services()
+    manifest = catalog.get(broker)
+    if manifest is None:
+        brokers = ", ".join(sorted(slug for slug, m in catalog.items() if m.kind == "mqtt-broker"))
+        raise ValueError(f"unknown iiot broker '{broker}'; known mqtt brokers: {brokers}")
+    if manifest.kind != "mqtt-broker":
+        raise ValueError(f"iiot broker '{broker}' is a '{manifest.kind}' service, not an mqtt-broker")
+    if manifest.wires is None or manifest.wires.mqtt is None:
+        raise ValueError(f"mqtt broker '{broker}' declares no wires.mqtt block, so the IIoT overlay cannot find its Transmission/Engine module slugs")
+    mqtt = manifest.wires.mqtt
+
+    # Add the broker instance once (id == slug); the resolver's singleton check
+    # catches an accidental duplicate broker elsewhere in the registry.
+    if not any(inst.id == broker for inst in config.service_instances):
+        config.service_instances.append(ServiceInstance(id=broker, service=broker))
+
+    transmission_gws = [gw for gw in config.gateways if gw.role in _TRANSMISSION_ROLES]
+    engine_gws = [gw for gw in config.gateways if gw.role in _ENGINE_ROLES]
+
+    if not transmission_gws and not engine_gws:
+        # No transmission/engine roles in this topology: run the whole loop on
+        # the single/first gateway so the demo is self-contained.
+        only = config.gateways[0]
+        _wire_iiot_gateway(only, broker, "mqtt-transmission", mqtt.transmission_module)
+        _wire_iiot_gateway(only, broker, "mqtt-engine", mqtt.engine_module)
+    else:
+        for gw in transmission_gws:
+            _wire_iiot_gateway(gw, broker, "mqtt-transmission", mqtt.transmission_module)
+        for gw in engine_gws:
+            _wire_iiot_gateway(gw, broker, "mqtt-engine", mqtt.engine_module)
+    return config
+
+
+def _wire_iiot_gateway(gw: GatewayConfig, instance_id: str, role: str, module: str) -> None:
+    """Attach ``gw`` to the broker with ``role`` and add ``module`` to it.
+
+    Role-aware guard (not the phase-1 instance-only ``_attach_all_gateways``): a
+    self-loop gateway holds two attachments to the same broker instance, one per
+    role, so the guard must key on the ``(instance, role)`` pair. Module presence
+    is guarded separately so a second pass adds nothing.
+    """
+    if not any(att.instance == instance_id and att.role == role for att in gw.services):
+        gw.services.append(ServiceAttachment(instance=instance_id, role=role))
+    if module not in gw.modules:
+        gw.modules.append(module)

ignition_stack-0.6.0/ignition_stack/architectures/basic.py

@@ -0,0 +1,45 @@
+"""Basic architecture: one full Ignition gateway + optional SQL DB.
+
+This mirrors Ignition's documented Basic architecture - a single gateway
+that does everything - surfaced as a named architecture so the wizard can
+offer it alongside the multi-gateway architectures. The only knobs are the
+database choice (defaults to Postgres) and the optional reverse-proxy
+scaffold.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ignition_stack.architectures.base import Architecture, ArchOptions, register
+from ignition_stack.config import DatabaseConfig, GatewayConfig, ProjectConfig
+
+
+@dataclass(frozen=True)
+class BasicArchitecture:
+    slug: str = "basic"
+    summary: str = "One full Ignition 8.3 gateway + Postgres. The default starter stack."
+
+    def build(self, name: str, options: ArchOptions) -> ProjectConfig:
+        gateway = GatewayConfig()
+        if options.edge_role in {"gateway", "basic"}:
+            gateway = gateway.model_copy(update={"ignition_edition": "edge"})
+
+        return ProjectConfig(
+            name=name,
+            architecture=self.slug,
+            gateways=[gateway],
+            database=_database(options),
+            services=list(options.services),
+            reverse_proxy=options.reverse_proxy,
+        )
+
+
+def _database(options: ArchOptions) -> DatabaseConfig | None:
+    if options.database_kind is None:
+        return None
+    return DatabaseConfig(kind=options.database_kind)
+
+
+# Side-effect: registers this architecture when the module is imported.
+architecture: Architecture = register(BasicArchitecture())