docs: close arch-review 08 drift batch — Commons Observability folder, site-repo exception, csproj separator, docs/components scope, DelmiaNotifier convention exception

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 06:57:34 -04:00
parent d61881ffaf
commit d8487eab2d
6 changed files with 13 additions and 2 deletions
@@ -51,6 +51,7 @@ Other peers in the `scadaproj` family (see `scadaproj/CLAUDE.md` for details): `
 - Each component document follows a consistent structure: Purpose, Location, Responsibilities, detailed design sections, Dependencies, and Interactions.
 - The README.md component table must stay in sync with actual component documents. When a component is added, removed, or renamed, update the table.
 - Cross-component references in Dependencies and Interactions sections must be kept accurate across all documents. When a component's role changes, update references in all affected documents.
+- Exception: DelmiaNotifier (#27) is an external client tool, not a cluster component; its spec is the project README (`src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier/README.md`) plus `docs/plans/2026-06-26-delmia-recipe-notifier-design.md` — there is intentionally no `Component-DelmiaNotifier.md`.

 ## Refinement Process

@@ -108,7 +108,7 @@ Both stacks share the infrastructure services in [`infra/`](infra/) (MS SQL, LDA

 ### Component Reference Documentation

-The design documents above are the **specs** (what each component does and why). For developer **reference** docs that describe how the shipped code works — with real code examples, drawn from `src/` and written to the [Style Guide](StyleGuide.md) — see [docs/components/](docs/components/). One doc per component (plus the shared TreeView), indexed in [docs/components/README.md](docs/components/README.md).
+The design documents above are the **specs** (what each component does and why). For developer **reference** docs that describe how the shipped code works — with real code examples, drawn from `src/` and written to the [Style Guide](StyleGuide.md) — see [docs/components/](docs/components/). Reference docs exist for 24 of the 27 components (plus the shared TreeView); ScriptAnalysis (#25), KpiHistory (#26), and DelmiaNotifier (#27) are pending — tracked in [docs/plans/2026-07-08-deferred-work-register.md](docs/plans/2026-07-08-deferred-work-register.md). Indexed in [docs/components/README.md](docs/components/README.md).

 ### Reference Documentation

@@ -5,6 +5,10 @@ code in `src/` actually works — with real code examples. These complement the
 [design specs](../requirements/) in `docs/requirements/`: the specs say what a
 component should do and why; these docs say how the code does it.

+Reference docs exist for 24 of the 27 components (plus the shared TreeView, listed below).
+ScriptAnalysis (#25), KpiHistory (#26), and DelmiaNotifier (#27) are pending — tracked in
+[../plans/2026-07-08-deferred-work-register.md](../plans/2026-07-08-deferred-work-register.md).
+
 | # | Component | Description |
 |---|-----------|-------------|
 | 1 | [Template Engine](TemplateEngine.md) | Template modeling, inheritance, composition, flattening, diffs, and semantic validation as implemented by the engine's services. |
@@ -291,6 +291,10 @@ ZB.MOM.WW.ScadaBridge.Commons/
 │   │                               #   SiteCallRelayMessages
 │   └── Management/                 # HTTP/ClusterClient management commands + registry,
 │                                   #   including TransportCommands (Export/Preview/Import bundle)
+├── Observability/                  # ScadaBridgeTelemetry — shared Meter ("ZB.MOM.WW.ScadaBridge") +
+│                                   #   counters/observable-gauges (deployments applied, inbound-API
+│                                   #   requests/abandoned execs, S&F replication failures, site
+│                                   #   connections up, S&F queue depth) with emit helpers
 ├── Serialization/                  # OpcUaEndpointConfigSerializer (typed↔legacy JSON)
 └── Validators/                     # OpcUaEndpointConfigValidator
 ```
@@ -167,6 +167,8 @@ Repository interfaces are defined in **Commons** alongside the POCO entity class

 Each implementation class uses the DbContext internally and works with the POCO entity classes from Commons. Consuming components depend only on Commons (for interfaces and entities) — they never reference this component or EF Core directly. The DI container in the Host wires the implementations to the interfaces.

+Site-side exception: read-only SQLite-backed implementations of shared repository interfaces live in `src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Repositories/` (currently `SiteExternalSystemRepository`) — same Commons interface, site-local store, writes throw `NotSupportedException` because site artifacts are managed exclusively by deployment from Central.
+
 #### Native Alarm Source Repository Methods

 `ITemplateEngineRepository` (implemented by `TemplateEngineRepository`) gains CRUD for both native alarm source entities, mirroring the existing alarm-override methods one-for-one:
@@ -23,6 +23,6 @@
    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.Communication/ZB.MOM.WW.ScadaBridge.Communication.csproj" />
    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.Security/ZB.MOM.WW.ScadaBridge.Security.csproj" />
    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.HealthMonitoring/ZB.MOM.WW.ScadaBridge.HealthMonitoring.csproj" />
-    <ProjectReference Include="..\ZB.MOM.WW.ScadaBridge.InboundAPI\ZB.MOM.WW.ScadaBridge.InboundAPI.csproj" />
+    <ProjectReference Include="../ZB.MOM.WW.ScadaBridge.InboundAPI/ZB.MOM.WW.ScadaBridge.InboundAPI.csproj" />
  </ItemGroup>
 </Project>