Joseph Doherty
c4d7ec9b96
Item 1 (owner decision: no signing). AuditLog:HashChain:HeadExport (default
off): both centrals periodically read every month's chain head (LastSeq,
LastHash, purge anchor, chained rows, tombstones; one snapshot under the
chain lock SHARED) and append the changed heads to a sink the DB login cannot
write - File (append-only JSONL per node per day, local or UNC) or Syslog
(RFC 5424 over UDP / TCP octet counting). `audit verify-heads --path` reads
those records back (file or syslog-collector lines) and the new
VerifyAuditChainHeads command checks each against the database: Matches /
Extended / Purged, or Mismatch / Regressed / MissingHead / MissingLink /
CountMismatch (exit 3). AuditChainHeadStoreTests forges a chain with the
production hasher: verify-chain says Intact, verify-heads says Mismatch.
Item 3. AuditLog:MaintenanceConnectionString (${secret:}-capable, unset =
today's single login) runs the chain job, chain verify / head export, the
partition switch-out + archive and the per-channel purge on
AuditMaintenanceContext (keyed audit-maintenance repository/archive, purge
actor prefers them). AuditMaintenanceLoginTests runs the hardened setup on
SQL Server: writer (datareader/datawriter/audit_writer) ingests and is
refused chaining and deleting; the chainer+purger login does the full cycle.
Two-login grants documented in Component-AuditLog.md.
Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
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 all 27 components (plus the shared TreeView, listed below).
| # | 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 | Script Analysis | The script trust model and validator, the diagnostics-only compile gate, the blocking-wait advisory, and the static flow-shape predictor. |
| 26 | KPI History | The central KpiHistoryRecorderActor singleton: KPI sampling, hourly rollups and backfill, and retention purge. |
| 27 | Delmia Notifier | The WWNotifier console client DELMIA shells out to, its YES/NO contract, and pre-execution-only failover. |
| 28 | 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.