docs: add human-facing repo README
Complements CLAUDE.md (the Claude-Code index) with a human overview: what's in here, the sister projects + data flow, the component- normalization concept, and the ZB.MOM.WW.Auth package/consumer matrix with build/test commands.
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,101 @@
|
||||
# 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 |
|
||||
| [`docs/plans/`](docs/plans/) | Implementation plans (e.g. the ZB.MOM.WW.Auth build) |
|
||||
| [`ZB.MOM.WW.Auth/`](ZB.MOM.WW.Auth/) | **Built shared library** (.NET 10) — the realized output of the auth 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/) |
|
||||
|
||||
## `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).
|
||||
- ⬜ Normalize the next cross-cutting component.
|
||||
Reference in New Issue
Block a user