dohertj2/ScadaBridge
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(components): index + link from README

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-03 15:59:20 -04:00
parent d14fc3f68f
commit a26f4a5f81
2 changed files with 46 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -2
View File
@@ -4,7 +4,7 @@ ScadaBridge is a centrally-managed, distributed SCADA configuration and deployme
## Overview
This repository is the full **implementation** project for ScadaBridge — the C#/.NET source (`src/`), tests (`tests/`), deployable Docker topology (`docker/`, `docker-env2/`, `infra/`), and the design documentation (`docs/`) that the code implements. This README is the master index: it links the per-component **design specs** (the spec the code in `src/` implements) and shows the system architecture. The solution file is `ZB.MOM.WW.ScadaBridge.slnx`.
This repository is the full **implementation** project for ScadaBridge — the C#/.NET source (`src/`), tests (`tests/`), deployable Docker topology (`docker/`, `docker-env2/`, `infra/`), and the design documentation (`docs/`) that the code implements. This README is the master index: it links the per-component **design specs** (the spec the code in `src/` implements), the per-component **reference docs** (how the shipped code works), and shows the system architecture. The solution file is `ZB.MOM.WW.ScadaBridge.slnx`.
### Technology Stack
@@ -32,7 +32,7 @@ This repository is the full **implementation** project for ScadaBridge — the C
|------|----------|
| `src/` | C#/.NET implementation — one project per component (`ZB.MOM.WW.ScadaBridge.<Component>`). Solution: `ZB.MOM.WW.ScadaBridge.slnx`. |
| `tests/` | Unit and integration test projects. |
| `docs/` | Design documentation — `docs/requirements/` (high-level + per-component specs, the spec the code implements), `docs/test_infra/`, `docs/plans/`. |
| `docs/` | Documentation — `docs/requirements/` (high-level + per-component specs, the spec the code implements), `docs/components/` (per-component developer reference — how the code works), `docs/test_infra/`, `docs/plans/`. |
| `docker/` | Primary 8-node cluster topology (2 central + 3 sites × 2 nodes + Traefik) + `deploy.sh`. |
| `docker-env2/` | Minimal second cluster (2 central + 1 site) for exercising Transport (#24) against a real second environment. |
| `infra/` | Local test services (MS SQL, LDAP, OPC UA, SMTP, REST API, Traefik). |
@@ -103,6 +103,10 @@ Both stacks share the infrastructure services in [`infra/`](infra/) (MS SQL, LDA
**Shared UI sub-component** (not a top-level component): [TreeView](docs/requirements/Component-TreeView.md) — reusable hierarchical tree/grid Blazor component used by the Central UI (#9) for the templates folder hierarchy, data-connection browse, and tag pickers.
### 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).
### Reference Documentation
- [AkkaDotNet/](AkkaDotNet/) — Akka.NET reference notes covering actors, remoting, clustering, persistence, streams, serialization, hosting, testing, and best practices.
docs/components/README.md
+40
View File
@@ -0,0 +1,40 @@
# 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](../requirements/) in `docs/requirements/`: the specs say what a
component should do and why; these docs say how the code does it.
| # | Component | Description |
|---|-----------|-------------|
| 1 | [Template Engine](TemplateEngine.md) | Template modeling, inheritance, composition, flattening, diffs, and semantic validation as implemented by the engine's services. |
| 2 | [Deployment Manager](DeploymentManager.md) | 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](SiteRuntime.md) | 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](DataConnectionLayer.md) | 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](Communication.md) | 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](StoreAndForward.md) | Site-only buffering, fixed-interval retry, parking, SQLite persistence, standby replication, and the operation-tracking store. |
| 7 | [External System Gateway](ExternalSystemGateway.md) | Script-facing HTTP/REST and database access, the `Call` and `CachedCall` modes, and transient versus permanent error classification. |
| 8 | [Notification Service](NotificationService.md) | Central notification-list and SMTP definitions, the per-type delivery adapters, and OAuth2 or Basic SMTP delivery. |
| 9 | [Central UI](CentralUI.md) | The Blazor Server app structure, authentication, real-time updates (SignalR and gRPC), and the management pages. |
| 10 | [Security & Auth](Security.md) | LDAP bind authentication, cookie and JWT sessions, role-based and site-scoped authorization, and shared Data Protection keys. |
| 11 | [Health Monitoring](HealthMonitoring.md) | Site metric collection and central aggregation, report and heartbeat intervals, offline detection, and dead-letter monitoring. |
| 12 | [Site Event Logging](SiteEventLogging.md) | The site-local SQLite event log, retention and storage cap, daily purge, and paginated central query access. |
| 13 | [Cluster Infrastructure](ClusterInfrastructure.md) | The `ClusterOptions` model and validation for active/standby clustering, split-brain resolution, and failover. |
| 14 | [Inbound API](InboundAPI.md) | `POST /api/{method}` script invocation, API-key authentication, the extended type system, and inbound-request auditing. |
| 15 | [Host](Host.md) | The deployable binary: role-based component registration, Akka bootstrap, ASP.NET Core hosting, and the readiness and active-node health endpoints. |
| 16 | [Commons](Commons.md) | Shared POCO entities, repository and service interfaces, message contracts, and the `Types`/`Interfaces`/`Entities`/`Messages` namespace layout. |
| 17 | [Configuration Database](ConfigurationDatabase.md) | The EF Core `DbContext`, repository implementations, the audit service, secret encryption, and migration and partition maintenance. |
| 18 | [Management Service](ManagementService.md) | The `ManagementActor` admin command surface, its HTTP endpoints, and ClusterClientReceptionist registration. |
| 19 | [CLI](CLI.md) | The System.CommandLine tool over the HTTP Management API — its command groups, config file, and output formats. |
| 20 | [Traefik Proxy](TraefikProxy.md) | The reverse proxy fronting the central cluster, active-node routing via `/health/active`, and the Docker topology configuration. |
| 21 | [Notification Outbox](NotificationOutbox.md) | The central `NotificationOutboxActor`, the `Notifications` table, the dispatcher loop, retry and parking, and KPIs. |
| 22 | [Site Call Audit](SiteCallAudit.md) | The central `SiteCallAuditActor`, the `SiteCalls` mirror table, telemetry ingest, and the parked-call Retry/Discard relay. |
| 23 | [Audit Log](AuditLog.md) | The append-only audit store: site SQLite hot-path, gRPC telemetry, central ingest and reconciliation, redaction, retention, and KPIs. |
| 24 | [Transport](Transport.md) | Encrypted bundle export and import, dependency resolution, conflict detection, and `BundleImportId`-correlated audit. |
| 25 | [Tree View](TreeView.md) | The reusable Blazor tree component — parameters, selection modes, and usage in the Central UI. |
## Related Documentation
- [Component design specs](../requirements/) — the spec each component implements.
- [Documentation Style Guide](../../StyleGuide.md) — the writing conventions these docs follow.
- [README](../../README.md) — the repository master index.