docs: render architecture & flow diagrams as draw.io charts

Replace ASCII-art diagrams across the README and docs/ with editable
.drawio sources plus exported PNGs, so the diagrams render clearly in
rendered markdown and can be maintained/regenerated instead of being
hand-edited as fragile text art. Non-diagram blocks (code, folder
trees, UI wireframes) were left as text.
This commit is contained in:
Joseph Doherty
2026-05-31 23:32:53 -04:00
parent 3763f6d2d8
commit bdee12f4e9
71 changed files with 2461 additions and 516 deletions
+6 -59
View File
@@ -92,20 +92,8 @@ The manifest is plaintext so the import wizard can preview bundle contents and s
## Architecture
```
ZB.MOM.WW.ScadaBridge.Transport
├── IBundleExporter
│ ExportAsync(ExportSelection, Passphrase?, ct) → Stream
├── IBundleImporter
│ LoadAsync(stream, Passphrase?, ct) → BundleSession
│ PreviewAsync(sessionId, ct) → ImportPreview
│ ApplyAsync(sessionId, resolutions, ct) → ImportResult
├── DependencyResolver
├── BundleSerializer (manifest + content JSON; ZIP packer)
├── BundleSecretEncryptor (AES-256-GCM + PBKDF2)
├── BundleSessionStore (in-memory, TTL'd)
└── ManifestValidator (schema/version gating, hash check)
```
![transport-architecture](diagrams/transport-architecture.png)
<!-- source: diagrams/transport-architecture.drawio — edit, then re-export with export-drawio.sh -->
The component is central-only. It is registered in `ZB.MOM.WW.ScadaBridge.Host` for central roles only, never for site roles. All persistence flows through existing audited repository interfaces in `ZB.MOM.WW.ScadaBridge.ConfigurationDatabase` — the component does not call `DbContext.SaveChangesAsync` directly. `BundleSessionStore` is in-process on the active central node (matching Blazor Server circuit affinity): 30-minute TTL, eviction on expiry, 3-strike passphrase lockout per session.
@@ -132,22 +120,8 @@ The user can toggle "include all dependencies" off (with a warning that the bund
### Backend
```
User (Design role) ─► Central UI Export wizard
IBundleExporter
├─► DependencyResolver ─► repositories (read)
├─► EntitySerializer ─► content.json
├─► BundleSecretEncryptor ► content.enc (if passphrase)
├─► ManifestBuilder ─► manifest.json
ZIP packer → temp file → browser download
IAuditService.LogAsync(BundleExported …)
```
![transport-export-flow](diagrams/transport-export-flow.png)
<!-- source: diagrams/transport-export-flow.drawio — edit, then re-export with export-drawio.sh -->
Audit event: `BundleExported` — caller, artifact count, content hash, encrypted yes/no, bundle filename.
@@ -179,35 +153,8 @@ Bundle references that cannot be satisfied in either the bundle or the target DB
### Backend
```
User (Admin role) ─► uploads bundle
IBundleImporter.LoadAsync
· verify SHA-256 (manifest vs content)
· check bundleFormatVersion supported
· decrypt content.enc with passphrase (if encrypted)
· deserialize entities
· open BundleSession (30-min TTL)
PreviewAsync → diff vs target DB → ImportPreview
▼ (user reviews + resolves conflicts)
ApplyAsync (single EF transaction)
· run two-tier semantic validation (minimal name scan + full SemanticValidator)
· apply resolutions (add / overwrite / skip / rename)
· upsert TemplateFolder hierarchy
· IAuditService.LogAsync(BundleImported …)
· commit
ImportResult → UI step 5
"View on Deployments →" (existing page)
```
![transport-import-flow](diagrams/transport-import-flow.png)
<!-- source: diagrams/transport-import-flow.drawio — edit, then re-export with export-drawio.sh -->
Authorization: `RequireAdmin` on both the Razor page and `IBundleImporter.*` entrypoints.