ScadaBridge/docs/plans/2026-05-28-scadabridge-rename-design.md

ScadaLink → ZB.MOM.WW.ScadaBridge Rename — Design

Date: 2026-05-28 Status: Approved, in implementation Scope: Repo-wide rename of the product from "ScadaLink" to "ScadaBridge" and addition of the ZB.MOM.WW company prefix to every .NET project. Code, runtime artifacts (containers, network, databases), docs, and CLI config.

Decisions

#	Decision	Selected option
1	Project / namespace format	ZB.MOM.WW.ScadaBridge.<Component> (both csproj filename and default namespace)
2	Runtime artifact rename	Full — containers scadabridge-*, network scadabridge-net, DBs ScadaBridge*, CLI config ~/.scadabridge/
3	Git rollout	Staged commits on main (3 commits: code → runtime → docs)
4	MS SQL DB migration	In-place ALTER DATABASE … MODIFY NAME (preserves data)
5	Site SQLite	Wipe on cutover (rm -rf docker/site-*/data per existing reset pattern)
6	Infra container scadalink-mssql	Rename to scadabridge-mssql + drop volume + re-seed (no cp between volumes)

Section 1 — Naming Map

Surface	Old	New
Solution file	ScadaLink.slnx	ZB.MOM.WW.ScadaBridge.slnx
Source projects (23)	src/ScadaLink.<C>/ScadaLink.<C>.csproj	src/ZB.MOM.WW.ScadaBridge.<C>/ZB.MOM.WW.ScadaBridge.<C>.csproj
Test projects (26)	tests/ScadaLink.<C>.Tests/…	tests/ZB.MOM.WW.ScadaBridge.<C>.Tests/…
Special tests	ScadaLink.IntegrationTests, ScadaLink.PerformanceTests, ScadaLink.Transport.IntegrationTests, ScadaLink.CentralUI.PlaywrightTests	gain ZB.MOM.WW.ScadaBridge. prefix; no component infix
Namespaces	namespace ScadaLink.<C>…	namespace ZB.MOM.WW.ScadaBridge.<C>…
Assembly names	(default = csproj name)	(default = csproj name)
DbContext	ScadaLinkDbContext	ScadaBridgeDbContext
MS SQL databases	ScadaLinkConfig, ScadaLinkMachineData, ScadaLinkConfig2, ScadaLinkMachineData2	ScadaBridgeConfig, ScadaBridgeMachineData, ScadaBridgeConfig2, ScadaBridgeMachineData2
Container names	scadalink-central-a, scadalink-env2-site-x-a, scadalink-mssql, …	scadabridge-central-a, scadabridge-env2-site-x-a, scadabridge-mssql, …
Docker network	scadalink-net	scadabridge-net
Docker image tag	scadalink:latest	scadabridge:latest
CLI config dir	~/.scadalink/config.json	~/.scadabridge/config.json
Top-level docs	CLAUDE.md, README.md, docs/**, deployments/**	rewritten in place

Explicitly NOT renamed:

• Transport.SourceEnvironment values (docker-cluster, docker-cluster-env2) — deployment IDs, not product names. Stable per deployments/.
• SQLite filenames (site_events.db, audit.db, S&F buffer) — already generic.
• Sister repos ~/Desktop/MxAccessGateway, ~/Desktop/OtOpcUa — out of scope.
• Repo folder ~/Desktop/scadalink-design — renaming it breaks Claude Code memory paths and the user's shell context. Folder name is allowed to diverge from product name.

Section 2 — Execution Mechanics

A scripted multi-pass substitution, committed to the repo at tools/rename-to-scadabridge.sh. Substitution order is most-specific-first to avoid double-replacement:

1. ScadaLinkDbContext          → ScadaBridgeDbContext
2. ScadaLinkMachineData        → ScadaBridgeMachineData
3. ScadaLinkConfig             → ScadaBridgeConfig
4. ScadaLink.                  → ZB.MOM.WW.ScadaBridge.
5. ScadaLink                   → ScadaBridge
6. scadalink-                  → scadabridge-
7. scadalink:                  → scadabridge:
8. .scadalink/                 → .scadabridge/

Each pass operates on git ls-files -z | xargs -0 sed -i '' so the .git/ directory and untracked artifacts are skipped.

Phases:

#	Phase	What runs
A	Generate	Write tools/rename-to-scadabridge.sh. Dry-run prints affected files.
B	Text pass	Steps 1–8. Content edits only; csproj filenames + folder names not yet moved. Build will fail at this point — expected.
C	Move files	git mv 23 src project folders + 26 test project folders, then each .csproj inside, then git mv ScadaLink.slnx ZB.MOM.WW.ScadaBridge.slnx.
D	Build & test	dotnet restore → dotnet build ZB.MOM.WW.ScadaBridge.slnx → unit-test pass. Fix stragglers (generated proto code, JSON identifiers with unexpected casing).
E	Runtime rename	docker/docker-compose.yml, docker-env2/docker-compose.yml, infra/docker-compose.yml, Dockerfile, all deploy/teardown/seed/build shell scripts, all appsettings.json connection strings. SQL rename script.
F	Redeploy & verify	bash docker/deploy.sh → bash docker-env2/deploy.sh → integration tests → CLI smoke (template list).
G	Docs & memory	CLAUDE.md, README.md, deployments/*.md, docs/plans/*.md, MEMORY.md references.

Completeness gate (end of phase D):

git grep -nE "ScadaLink|scadalink" -- ':!*.md' ':!CLAUDE.md' | grep -v "docs/plans/2026-05-28-scadabridge-rename"

Must return zero hits in code/config. Docs and this design doc are allowed to mention the old name for historical context.

Commit sequence:

1. refactor: rename ScadaLink → ZB.MOM.WW.ScadaBridge (code + projects + namespaces) — phases B+C+D
2. refactor: rename runtime artifacts to scadabridge (containers, network, DBs, image tag) — phases E+F
3. docs: rename ScadaLink → ScadaBridge across CLAUDE.md, README, deployments, plans — phase G

git diff review between each commit.

Section 3 — Database Migration

MS SQL — in-place rename, no data loss:

USE master;
ALTER DATABASE ScadaLinkConfig        MODIFY NAME = ScadaBridgeConfig;
ALTER DATABASE ScadaLinkMachineData   MODIFY NAME = ScadaBridgeMachineData;
ALTER DATABASE ScadaLinkConfig2       MODIFY NAME = ScadaBridgeConfig2;
ALTER DATABASE ScadaLinkMachineData2  MODIFY NAME = ScadaBridgeMachineData2;

Wrapped in docker/rename-databases.sh; docker-env2/init-db.sh updated to create the new names going forward. EF Core doesn't store the database name in the model snapshot, so no migration is required.

Site SQLite — wipe on cutover:

rm -rf docker/site-*/data docker/central-*/data
rm -rf docker-env2/site-*/data docker-env2/central-*/data

Run before redeploy in phase F. The seed-sites scripts re-create site rows; S&F buffers and event logs start empty. Matches the existing reset pattern documented in docker/README.md.

Infra container scadalink-mssql:

Drop volume + re-seed. docker compose -f infra/docker-compose.yml down -v then up -d. Test data is dev-only and seed scripts are fast — preferred over copying volume data. Same approach for LDAP (config-file driven), SMTP (ephemeral by design), OPC UA (config-file driven), REST API (stateless).

Out of Scope

• Sister repos ~/Desktop/MxAccessGateway, ~/Desktop/OtOpcUa — independent codebases, independent timelines.
• Repo folder ~/Desktop/scadalink-design — left as-is to preserve Claude Code memory paths and user shell context.
• Existing Transport bundle manifests with SourceEnvironment = "docker-cluster" — those values are deployment IDs and stay stable. If the user later wants to rename the deployment IDs themselves, that's a separate design.

Verification

After all three commits:

• dotnet build ZB.MOM.WW.ScadaBridge.slnx clean
• dotnet test — unit + integration suites green (pre-existing flakes documented in earlier code-review remediation sessions remain accepted)
• curl -s http://localhost:9000/health/ready and http://localhost:9100/health/ready both report healthy on the renamed primary + env2 stacks
• CLI smoke: dotnet run --project src/ZB.MOM.WW.ScadaBridge.CLI -- --username multi-role --password password template list against both stacks
• git grep -nE "ScadaLink|scadalink" returns only this design doc and intentional historical references in committed plans