Joseph Doherty
69b3ccfc37
CLAUDE.md was corrected in34227991but the component docs were not, so the same understatements — plus several outright wrong statements — survived where a reader is most likely to meet them. ClusterInfrastructure.md carried the worst of it. It described active/standby as cluster leadership and showed an IsActiveNode snippet doing `cluster.State.Leader == self.Address`. No such code exists: ActiveNodeGate returns ClusterActivityEvaluator.SelfIsOldest, and ActiveNodeEvaluator's own doc comment says "never cluster.State.Leader". A second snippet (siteCallAuditShutdown .AddTask) described a hand-rolled drain that has since been folded into SingletonRegistrar.Start. Both snippets are replaced with what the code does. The central singleton table listed 3 of the 7 registered singletons. The downing section still described keep-oldest as the strategy and omitted downing-provider-class entirely; it now shows the branching blockcf3bd52fintroduced, with the accepted dual-active trade stated rather than the old "impossible to boot" framing. Note the requirements-side spec, docs/requirements/Component-ClusterInfrastructure.md, was already rewritten bycf3bd52f— this is the components-side doc, which was untouched. Communication.md described two transports; there are three — the deployment config fetch over HTTP was missing. Each row now names which side dials, because the gRPC entry gave a data direction (site to central) without saying who hosts the server, which reads as the opposite of the truth: the only MapGrpcService in the tree is in Program.cs's Site branch, and central dials in. The SiteEnvelope snippet called DeployInstanceAsync, which is not a member of CommunicationService; the heartbeat bullet claimed a cluster-leadership check; the proto summary listed 4 of 6 RPCs. DeploymentManager.md still said the pipeline sends DeployInstanceCommand carrying FlattenedConfigurationJson. It stages a PendingDeployment and sends a RefreshDeploymentCommand; the config travels over the HTTP fetch. That is the change the 128 KB frame-size issue forced, and the doc predated it. Two of the five briefed drifts turned out not to be errors: nothing claimed the transports were authenticated, and nothing asserted per-site ActorSystem names — both were simply unstated. They are now stated, since silence about an unauthenticated boundary is its own problem. Docs only; no code changed. Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
Component Reference Documentation
Developer-reference docs for each ScadaBridge component, describing how the shipped
code in src/ actually works — with real code examples. These complement the
design specs 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.
| # | Component | Description |
|---|---|---|
| 1 | Template Engine | Template modeling, inheritance, composition, flattening, diffs, and semantic validation as implemented by the engine's services. |
| 2 | Deployment Manager | The central deployment pipeline: deployment identity and idempotency, per-instance operation locks, state transitions, all-or-nothing site apply, and artifact deployment. |
| 3 | Site Runtime | The site actor hierarchy (Deployment Manager singleton, Instance, Script, and Alarm actors), script compilation and execution, the site-wide stream, native alarms, and supervision. |
| 4 | Data Connection Layer | Protocol adapters (OPC UA, MxGateway), the Become/Stash connection state machine, reconnect and re-subscribe, and the native-alarm subscription seam. |
| 5 | Central–Site Communication | ClusterClient command and control plus gRPC server-streaming, the central and site communication actors, receptionist registration, and per-site contact points. |
| 6 | Store-and-Forward Engine | Site-only buffering, fixed-interval retry, parking, SQLite persistence, standby replication, and the operation-tracking store. |
| 7 | External System Gateway | Script-facing HTTP/REST and database access, the Call and CachedCall modes, and transient versus permanent error classification. |
| 8 | Notification Service | Central notification-list and SMTP definitions, the per-type delivery adapters, and OAuth2 or Basic SMTP delivery. |
| 9 | Central UI | The Blazor Server app structure, authentication, real-time updates (SignalR and gRPC), and the management pages. |
| 10 | Security & Auth | LDAP bind authentication, cookie and JWT sessions, role-based and site-scoped authorization, and shared Data Protection keys. |
| 11 | Health Monitoring | Site metric collection and central aggregation, report and heartbeat intervals, offline detection, and dead-letter monitoring. |
| 12 | Site Event Logging | The site-local SQLite event log, retention and storage cap, daily purge, and paginated central query access. |
| 13 | Cluster Infrastructure | The ClusterOptions model and validation for active/standby clustering, split-brain resolution, and failover. |
| 14 | Inbound API | POST /api/{method} script invocation, API-key authentication, the extended type system, and inbound-request auditing. |
| 15 | Host | The deployable binary: role-based component registration, Akka bootstrap, ASP.NET Core hosting, and the readiness and active-node health endpoints. |
| 16 | Commons | Shared POCO entities, repository and service interfaces, message contracts, and the Types/Interfaces/Entities/Messages namespace layout. |
| 17 | Configuration Database | The EF Core DbContext, repository implementations, the audit service, secret encryption, and migration and partition maintenance. |
| 18 | Management Service | The ManagementActor admin command surface, its HTTP endpoints, and ClusterClientReceptionist registration. |
| 19 | CLI | The System.CommandLine tool over the HTTP Management API — its command groups, config file, and output formats. |
| 20 | Traefik Proxy | The reverse proxy fronting the central cluster, active-node routing via /health/active, and the Docker topology configuration. |
| 21 | Notification Outbox | The central NotificationOutboxActor, the Notifications table, the dispatcher loop, retry and parking, and KPIs. |
| 22 | Site Call Audit | The central SiteCallAuditActor, the SiteCalls mirror table, telemetry ingest, and the parked-call Retry/Discard relay. |
| 23 | Audit Log | The append-only audit store: site SQLite hot-path, gRPC telemetry, central ingest and reconciliation, redaction, retention, and KPIs. |
| 24 | Transport | Encrypted bundle export and import, dependency resolution, conflict detection, and BundleImportId-correlated audit. |
| 25 | Tree View | The reusable Blazor tree component — parameters, selection modes, and usage in the Central UI. |
Related Documentation
- Component design specs — the spec each component implements.
- Documentation Style Guide — the writing conventions these docs follow.
- README — the repository master index.