scadaproj/README.md

# scadaproj

Umbrella workspace for a family of related **SCADA / OT** (operational-technology) projects
built around **AVEVA System Platform (Wonderware)**, **OPC UA**, and **Akka.NET**.

This repository is part **index** — a map of the sister projects, which are their own
repositories — and part **home** for cross-project *normalization* work and the shared code
it produces.

> Working in here with Claude Code? See [`CLAUDE.md`](CLAUDE.md) for the machine-oriented
> index and guidance. This README is the human-facing overview.

## What's in here

| Path | What it is |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | High-level index of the sister projects + working guidance |
| [`components/`](components/) | Component-normalization framework (per concern: target spec, current state, gaps) |
| [`components/auth/`](components/auth/) | First normalized component — login / identity / authorization |
| [`components/ui-theme/`](components/ui-theme/) | Second normalized component — UI theme / design tokens / layout |
| [`docs/plans/`](docs/plans/) | Implementation plans (e.g. the ZB.MOM.WW.Auth and ZB.MOM.WW.Theme builds) |
| [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | **Built shared library** (.NET 10) — the realized output of the auth normalization |
| [`ZB.MOM.WW.Theme/`](ZB.MOM.WW.Theme/) | **Built shared RCL** (.NET 10) — the realized output of the UI-theme normalization |

## The sister projects

Independent repositories, coupled only at **runtime over wire protocols** (gRPC + OPC UA) —
not by a shared build. scadaproj *indexes* them; it does not contain them.

- **OtOpcUa** (`lmxopcua`) — OPC UA server (.NET 10) that republishes Wonderware Galaxy tags as
  an OPC UA address space.
- **MxAccessGateway** (`mxaccessgw`) — gRPC gateway giving modern x64 / .NET-10 clients full
  MXAccess parity without loading 32-bit COM. The linchpin both others depend on.
- **ScadaBridge** — distributed SCADA platform on Akka.NET (hub-and-spoke: one central cluster
  + N site clusters); its Data Connection Layer ingests OPC UA and MxAccess.

Data flow:

```
Wonderware Galaxy ──gRPC──▶ mxaccessgw ──▶ OtOpcUa (republishes as OPC UA) ─┐
                                       └────────────────────────────────────┴─▶ ScadaBridge clusters
                                          (or ScadaBridge's MxGateway adapter, direct)
```

Full relationship map: [`CLAUDE.md`](CLAUDE.md#cross-project-relationships).

## Component normalization

The sister repos kept re-implementing the same cross-cutting concerns and drifting apart.
[`components/`](components/) captures, per component, the **one target** spec, each project's
**code-verified current state**, and a **gaps / adoption backlog**. Convention + workflow in
[`components/README.md`](components/README.md).

| Component | Status | Folder |
|---|---|---|
| Auth (login / identity / authz) | Built (library 0.1.0); apps not yet adopted | [`components/auth/`](components/auth/) |
| UI Theme (layout / tokens / components) | Built (RCL 0.1.0); apps not yet adopted | [`components/ui-theme/`](components/ui-theme/) |

## `ZB.MOM.WW.Theme` — the shared UI kit

The UI-theme component, realized as a single-package .NET 10 Razor Class Library the three
apps can adopt to stop copy-pasting the Technical-Light design system. **Built and tested at
0.1.0; adoption by the apps is the follow-on** (tracked in
[`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md)).

| Asset / Component | Purpose | Used by |
|---|---|---|
| `_content/ZB.MOM.WW.Theme/css/theme.css` | Design tokens, IBM Plex typography, Bootstrap overrides | all |
| `_content/ZB.MOM.WW.Theme/css/layout.css` | Side-rail shell layout, nav CSS, chip/card helpers | all |
| `_content/ZB.MOM.WW.Theme/fonts/*.woff2` | IBM Plex Sans 400/600 + Mono 500, vendored | all |
| `ThemeHead`, `ThemeShell`, `BrandBar` | Shell entry point and chassis components | all |
| `NavRailItem`, `NavRailSection` | Rail nav components | all |
| `StatusPill` (`StatusState`) | Inline status chip — replaces per-app `StatusBadge` | all |
| `LoginCard` | Static form-POST sign-in card | OtOpcUa, ScadaBridge (MxGateway when login page added) |
| `TechButton`, `TechCard`, `TechField` | Common controls (Bootstrap 5 wrappers) | all |

**Consumer matrix:** all three apps consume the single `ZB.MOM.WW.Theme` package —
OtOpcUa `AdminUI`, MxAccessGateway `Server`, ScadaBridge `Host` + `CentralUI`.

### Build & test

```bash
cd ZB.MOM.WW.Theme
dotnet build -c Release   # 0 warnings (TreatWarningsAsErrors)
dotnet test               # 32 bUnit tests
./build/pack.sh           # → ./artifacts/ZB.MOM.WW.Theme.0.1.0.nupkg
```

Stack: .NET 10 · Razor Class Library · bUnit · xUnit · central package management.
More detail: [`ZB.MOM.WW.Theme/README.md`](ZB.MOM.WW.Theme/README.md).

---

## `ZB.MOM.WW.Auth` — the shared library

The auth component, realized as a four-package .NET 10 library the three apps can adopt to stop
re-implementing authentication. **Built and tested at 0.1.0; adoption by the apps is the
follow-on** (tracked in [`components/auth/GAPS.md`](components/auth/GAPS.md)).

| Package | Purpose | Used by |
|---|---|---|
| `ZB.MOM.WW.Auth.Abstractions` | Contracts, `CanonicalRole`, API-key types (zero deps) | all |
| `ZB.MOM.WW.Auth.Ldap` | Bind-then-search LDAP authentication (fail-closed) | all |
| `ZB.MOM.WW.Auth.ApiKeys` | Peppered-HMAC API keys + SQLite store + verifier + admin commands | MxAccessGateway, ScadaBridge |
| `ZB.MOM.WW.Auth.AspNetCore` | Canonical claim types, cookie defaults, LDAP DI helpers | all (web UIs) |

**Consumer matrix:** OtOpcUa → `Abstractions + Ldap + AspNetCore` (no ApiKeys / SQLite);
MxAccessGateway & ScadaBridge → all four.

Identity (LDAP / GLAuth, the canonical role set) is normalized; each app keeps its own
**authorization enforcement** (OPC-UA permissions / gRPC scopes / roles + site-scoping) and maps
it onto the canonical roles. Design: [`components/auth/spec/SPEC.md`](components/auth/spec/SPEC.md)
and [`CANONICAL-ROLES.md`](components/auth/spec/CANONICAL-ROLES.md).

### Build & test

```bash
cd ZB.MOM.WW.Auth
dotnet build -c Release                 # 0 warnings
dotnet test                             # 172 passing, 1 skipped (opt-in LDAP integration test)
dotnet pack  -c Release -o ./artifacts  # → 4 nupkgs @ 0.1.0
```

Stack: .NET 10 · xUnit · `Novell.Directory.Ldap.NETStandard` · `Microsoft.Data.Sqlite` · central
package management. The packages are **libraries linked into each consumer** — there is **no
central auth service**. More detail: [`ZB.MOM.WW.Auth/README.md`](ZB.MOM.WW.Auth/README.md).

The optional LDAP integration test is opt-in:

```bash
ZB_LDAP_IT=1 dotnet test   # requires a reachable GLAuth (e.g. a sister repo's infra/glauth)
```

## Roadmap

- ✅ Auth component normalized (spec + canonical roles + current-state + gaps).
- ✅ `ZB.MOM.WW.Auth` shared library built and tested (0.1.0).
- ⬜ Adopt `ZB.MOM.WW.Auth` in OtOpcUa, MxAccessGateway, ScadaBridge — [`components/auth/GAPS.md`](components/auth/GAPS.md) (#8).
- ✅ UI-theme component normalized (spec + design tokens + current-state + gaps).
- ✅ `ZB.MOM.WW.Theme` shared UI kit built and tested (0.1.0); apps not yet adopted.
- ⬜ Adopt `ZB.MOM.WW.Theme` in OtOpcUa [low risk], ScadaBridge [med], MxAccessGateway [high risk] — [`components/ui-theme/GAPS.md`](components/ui-theme/GAPS.md).
- ⬜ Normalize the next cross-cutting component.