lmxopcua/lmx_backend.md

> **✅ Completed 2026-04-30 — historical record of the v2-mxgw backend-options decision.**
>
> This document evaluated alternative backend topologies before the
> v2-mxgw migration. **Option 1 (in-process driver + gRPC gateway) was
> selected and implemented**; see `lmx_mxgw.md` for the design and
> `lmx_mxgw_impl.md` for the implementation plan. Both shipped at
> commit `ae7106d` (2026-04-30). Preserved here as the audit trail.

# Galaxy / LMX Backend — Restructuring Options

## Context

Today the Galaxy driver is structured very differently from every other driver
in this repo:

- **Galaxy.Proxy** (.NET 10, in-process): tiny shim that frames IPC to the host.
- **Galaxy.Host** (.NET Framework 4.8 **x86**, NSSM-wrapped Windows service):
  owns MXAccess COM, the STA pump, the ZB Galaxy Repository SQL queries, the
  Wonderware Historian SDK plugin, the per-platform `ScanState` probe manager,
  the alarm tracker (`.InAlarm`/`.Priority`/`.DescAttrName`/`.Acked` state
  machine + ack writer), recycle policy, and post-mortem MMF.

Other drivers (Modbus, S7, AB CIP, OpcUaClient, TwinCAT, FOCAS Tier-C) are
**in-process Tier-A drivers** in the .NET 10 server. They do data + browse
only; historian and alarming are driver-agnostic concerns at the server layer.

A sibling project, **mxaccessgw**
(`C:\Users\dohertj2\Desktop\mxaccessgw`), already provides:

- A .NET 10 x64 gRPC gateway in front of per-session .NET 4.8 x86 worker
  processes that own MXAccess COM, the STA, and event sinks
  (`MxGateway.Server` + `MxGateway.Worker`).
- A full MXAccess command + event surface (`Register`, `AddItem`, `Advise`,
  `Write`, `WriteSecured`, `OnDataChange`, `OnWriteComplete`, etc.).
- A cached, deploy-gated, paged **Galaxy Repository browse** RPC
  (`galaxy_repository.v1`) reading the same ZB tables we read today, with the
  query bodies kept byte-identical to OtOpcUa.
- A .NET client library (`clients/dotnet/MxGateway.Client`).
- API-key auth, Blazor dashboard, structured logs, metrics, watchdog/recycle.

The proposal is to **strip Galaxy down to data + browse** — push historian and
alarming out to server-level subsystems where they live for every other driver
— and pick how the slimmed-down driver talks to MXAccess.

---

## What "push historian and alarming out" means

Both options below assume the same scope reduction; they only differ in how
the driver reaches MXAccess.

| Concern | Today (Galaxy.Host) | After |
|---|---|---|
| Galaxy hierarchy browse | `GalaxyRepository` (SQL) inside Host | Driver (Option 1: via gw browse RPC; Option 2: own SQL or worker) |
| Live read / write / subscribe | `MxAccessClient` + STA pump in Host | gw (Option 1) or embedded worker (Option 2) |
| Wonderware Historian SDK | `HistorianDataSource` in Host (x86) | Separate Historian data source plugged into the server's HA service. Likely stays its own .NET 4.8 x86 sidecar because the SDK is x86-only; **independent of the Galaxy driver lifecycle**. |
| Alarm state machine (`.InAlarm`/`.Acked` quartet, transitions, ack writer) | `GalaxyAlarmTracker` in Host | Server-level A&E subsystem subscribes to alarm-bearing attributes the driver advertises and runs the AlarmCondition state machine generically. Driver only flags `IsAlarm=true` in node metadata. |
| `ScanState` per-platform probes | `GalaxyRuntimeProbeManager` in Host | Driver-side: ScanState is just another tag subscription; the driver re-advises one per discovered `$WinPlatform`/`$AppEngine` and reports `HostConnectivityStatus` from the value stream. No special host-side machinery. |

After the strip-down, the Galaxy driver looks like Modbus or OpcUaClient: it
discovers nodes, reads/writes/subscribes, and reports per-host transport
health. Everything else is the server's problem.

---

## Option 1 — Tier-A driver against the MxAccess Gateway

`Driver.Galaxy` becomes a regular **in-process .NET 10 driver** in the OtOpcUa
server (no `.Host`, no `.Proxy` split, no x86). It talks to a separately
deployed `MxGateway.Server` over gRPC using `MxGateway.Client`. Browse comes
from `galaxy_repository.v1.DiscoverHierarchy`. Live data comes from
`MxAccessGateway.OpenSession`/`AddItem`/`Advise`/`StreamEvents`.

```
OtOpcUa.Server (.NET 10 x64)
  └── Driver.Galaxy (in-proc, .NET 10)
        └── gRPC ──► MxGateway.Server (.NET 10 x64)
                       └── pipe ──► MxGateway.Worker (.NET 4.8 x86)
                                       └── MXAccess COM (STA)
```

### Pros

- **Architectural parity with other drivers.** No bespoke `Host` service, no
  x86 build target, no NSSM wrapper, no STA pump in this repo, no
  `PostMortemMmf`/`RecyclePolicy` we maintain ourselves.
- **OtOpcUa server stops needing AVEVA installed on its own host.** The
  gateway runs where MXAccess lives; the OPC UA server can live on a different
  box, in a container, or on a hardened jump host.
- **One canonical MXAccess surface across the org.** Any future tool — a
  diagnostic CLI, a Historian replacement, an integration harness — talks to
  the same gw with the same parity guarantees we get.
- **Multi-instance friendly.** Two OtOpcUa servers (warm/hot redundancy) share
  one gw and one MXAccess footprint instead of each running their own
  `Galaxy.Host` with duplicate Wonderware client identities.
- **Browse + cache for free.** `galaxy_repository.v1` already implements the
  hierarchy cache, deploy-time gating, paging, and `WatchDeployEvents` — we
  delete `GalaxyRepository.cs`, `GalaxyHierarchyRow.cs`, the change-detection
  poll loop, and the matching SQL plumbing.
- **Operability for free.** API-key auth, Blazor dashboard at `/dashboard`,
  metrics via `Meter`, structured logs with redaction. We currently have
  none of that in `Galaxy.Host`.
- **Future backend swap.** When AVEVA exposes managed NMX or another modern
  path, gw routes to it without OtOpcUa changes (gw's stated roadmap).
- **Tighter blast radius.** A hung COM event, a leaking COM object, a
  crashing worker — all owned by gw's session/worker isolation, not the
  OPC UA server process.
- **Simpler version story for OtOpcUa.** Driver is plain .NET 10; the
  bitness/runtime split lives entirely in mxaccessgw's repo.

### Cons

- **Extra deployment dependency.** mxaccessgw is now a service that has to be
  installed, monitored, and kept on a compatible protocol version. For a
  single-box install this is one more moving piece.
- **Two hops on every call** (driver→gw, gw→worker) instead of one
  (proxy→host). Today's hop is MessagePack over a named pipe; the new outer
  hop is gRPC over TCP. Per-call overhead is a few hundred microseconds, not
  a regression for OPC UA workloads but measurable for very chatty bursts.
- **Auth/secret surface added.** OtOpcUa now holds an API key for gw and
  rotates it; gw's SQLite-backed key store has to be managed.
- **Failure model spans two processes we don't own** — gw + worker. Reconnect
  logic in our driver has to ride both: gw transport drop, gw session lease
  expiry, gw-detected worker crash, plus the worker's own MXAccess reconnect.
  All of it is exposed in the gRPC contract, but it's still surface area.
- **Cross-repo protocol coupling.** Bumping `mxaccessgw` major version (gRPC
  contract changes, session shape changes) ripples into OtOpcUa releases.
  Mitigated by versioned contracts; not free.
- **Galaxy redundancy still has to think about gw.** A redundancy fail-over of
  OtOpcUa is independent of the gw's session lifecycle. Need to decide whether
  the standby holds an open session or only opens it on takeover.
- **Sensitive writes (`WriteSecured`, `AuthenticateUser`) cross the network**
  if gw is remote. TLS + mTLS solves it but adds setup.

---

## Option 2 — Embed mxaccessgw worker, no gateway

`Driver.Galaxy` is still in-process .NET 10, but instead of speaking gRPC to a
gateway service, it directly **launches and supervises one (or more)
`MxGateway.Worker` processes** and talks to them over the same named-pipe
worker protocol gw uses internally
(`docs/WorkerFrameProtocol.md`, `docs/WorkerProcessLauncher.md`). Browse stays
local — driver runs the SQL queries against ZB itself.

```
OtOpcUa.Server (.NET 10 x64)
  └── Driver.Galaxy (in-proc, .NET 10)
        ├── ZB SQL (local, in-proc)
        └── pipe ──► MxGateway.Worker (.NET 4.8 x86, child process)
                       └── MXAccess COM (STA)
```

### Pros

- **One hop, not two.** Driver → worker pipe is the same shape as today's
  Proxy → Host pipe. Latency is on par with the current implementation.
- **No new service to deploy.** Worker is launched as a child process the
  same way `Galaxy.Host` is launched today (just with mxaccessgw's worker
  binary). Single-machine install story stays simple.
- **Keeps the trust boundary local.** No API keys, no TLS, no exposed gRPC
  port on the OtOpcUa box.
- **Reuses mxaccessgw's parity-tested worker code** — STA pump, COM lifetime,
  event conversion, fault model — without inheriting gw's ASP.NET Core /
  Blazor / SQLite footprint.
- **Tighter ownership.** OtOpcUa owns the worker lifecycle; recycle, kill,
  restart, post-mortem all decided by the driver, not by an external service
  we don't control.
- **Easier to reason about during integration tests.** No second service to
  spin up in CI; just a child process per test fixture.

### Cons

- **OtOpcUa server box must still have AVEVA + MXAccess installed**, since
  the worker runs locally. The major deployment win of Option 1
  (separating where MXAccess runs from where OtOpcUa runs) is lost.
- **OtOpcUa still ships an x86 .NET 4.8 binary alongside it.** Even if we
  vendor mxaccessgw's worker rather than write our own, installer complexity
  and bitness considerations remain.
- **We re-implement everything gw already gives.** Process supervision,
  watchdog, recycle policy, heartbeat, post-mortem — these are exactly what
  `Galaxy.Host` does today, and they'd live in our repo again, just calling a
  different worker binary.
- **No browse cache, no deploy gating, no `WatchDeployEvents`** — we keep
  running our own ZB queries and our own `time_of_last_deploy` poll, or we
  port gw's cache code into the driver. Either way it's duplicated logic.
- **No auth, no dashboard, no metrics.** Operability stays where it is today
  (i.e., minimal). Adding it ourselves is a separate project.
- **Multiple OtOpcUa instances multiply MXAccess sessions.** Redundancy pair
  → two MXAccess clients on the Galaxy from the same software, vs. Option 1
  where one gw arbitrates.
- **Worker protocol coupling without the contract surface.** We depend on
  mxaccessgw's worker IPC frame format — a surface that mxaccessgw treats as
  *internal* to its own gw↔worker boundary. If they refactor it, we have to
  follow. The public gRPC contract (Option 1) is more stable by design.
- **Loses the "common MXAccess access point" benefit.** Other consumers
  (CLI, integration harnesses, future tools) can't share state with our
  embedded worker.

---

## Status quo (for comparison)

Keep `Galaxy.Host` as today, and in-place rip out historian + alarming +
probe manager. End state: the Host shrinks to `MxAccessClient` + `GalaxyRepository`,
which is roughly what Option 2 ends up looking like — but with our hand-rolled
COM bridge instead of mxaccessgw's worker. Not a serious option once
mxaccessgw exists; we'd be maintaining a parallel implementation of the same
thing.

---

## Recommendation (effort-agnostic)

**Go with Option 1 — Tier-A driver against the MxAccess Gateway.**

The decisive arguments:

1. **It's the only option that aligns Galaxy with how every other driver in
   this repo is structured.** The user's stated goal — "keep lmx to data +
   browsing, similar to other drivers" — only fully resolves if there is no
   `.Host` and no x86 build artifact in this repo at all. Option 2 still has
   an x86 child process and supervisor code; it's `Galaxy.Host` with a
   different worker binary inside.

2. **It separates *where MXAccess runs* from *where OtOpcUa runs*.** That is
   a strategically larger win than a few hundred microseconds of per-call
   latency. The OPC UA server stops being chained to AVEVA install footprint,
   bitness, and Wonderware client identity — which removes a class of
   deployment, redundancy, and CI problems we hit today (e.g., the
   `DESKTOP-6JL3KKO` Hyper-V/Docker conflict, the `dohertj2`-only pipe ACL,
   the live-Galaxy smoke test prerequisites).

3. **It collapses scope.** A non-trivial fraction of `Galaxy.Host` (browse
   cache, deploy-event watch, worker supervision, COM bridge, post-mortem,
   recycle, ACL hardening) is reproduced *better* in mxaccessgw. Option 1
   deletes our copy. Option 2 keeps it.

4. **It positions historian and alarming for the right home.** Once the
   Galaxy driver is "just another driver", historian becomes a server-level
   data source (one that can also feed Modbus/S7 history if we ever want it),
   and alarming becomes a server-level A&E subsystem. Option 2 nominally
   allows the same move, but the temptation to keep them in `Galaxy.Host`
   "while we're already there" is real.

5. **It future-proofs against AVEVA's roadmap.** Managed NMX, ASB, or any
   replacement that shows up over the next few years gets adopted in
   mxaccessgw without a release in this repo.

The case for Option 2 is real but narrow: it's the right call **only** if we
commit to single-box deployments forever, refuse to take a gRPC dependency,
and value local-trust simplicity over the consolidation/operability benefits
gw provides. None of those constraints hold here.

### What flips the recommendation

- If the gw protocol is unstable or perf-tested under our subscription
  patterns turns out worse than expected → revisit Option 2.
- If org-policy forbids running an MXAccess gateway as its own service →
  Option 2.
- If Galaxy goes from one of several drivers to *the* primary driver and
  raw call-rate matters more than architectural fit → revisit.

Otherwise: Option 1.

---

## Out-of-scope follow-ups (don't decide here, but flag them)

- **Where does the Wonderware Historian SDK live?** Likely its own
  .NET 4.8 x86 sidecar exposing a small `IHistorianDataSource` over a pipe or
  gRPC, plugged into the OPC UA server's HA service alongside any future
  historian sources. Independent of which option above is chosen.
- **Alarm subsystem ownership.** Decide whether the server hosts a generic
  AlarmCondition state machine driven by driver-advertised alarm metadata, or
  whether each driver continues to emit pre-shaped alarm transitions. Galaxy's
  4-attr quartet is a strong forcing function for the generic approach.
- **Redundancy + gw sessions.** Standby OtOpcUa holds an open gw session
  (warm) vs. opens on takeover (cold). Affects gw worker count and Galaxy
  client-identity collisions.
- **Auth between OtOpcUa and gw.** API key in DPAPI-protected secret file vs.
  Windows-auth gRPC. Both supported by gw; pick before rollout.