Add Management Service and CLI components (design docs)

New components 18-19: ManagementService (Akka.NET actor on Central exposing
all admin operations via ClusterClientReceptionist) and CLI (console app using
ClusterClient for scripting). Updated HighLevelReqs, CLAUDE.md, README,
Component-Host, Component-Communication, Component-Security.
This commit is contained in:
Joseph Doherty
2026-03-17 14:28:02 -04:00
parent 7dcdcc46c7
commit 50dad61e72
8 changed files with 410 additions and 6 deletions

View File

@@ -32,7 +32,7 @@ The same compiled binary must be deployable to both central and site nodes. The
At startup the Host must inspect the configured node role and register only the component services appropriate for that role:
- **Shared** (both Central and Site): ClusterInfrastructure, Communication, HealthMonitoring, ExternalSystemGateway, NotificationService.
- **Central only**: TemplateEngine, DeploymentManager, Security, AuditLogging, CentralUI, InboundAPI.
- **Central only**: TemplateEngine, DeploymentManager, Security, AuditLogging, CentralUI, InboundAPI, ManagementService.
- **Site only**: SiteRuntime, DataConnectionLayer, StoreAndForward, SiteEventLogging.
Components not applicable to the current role must not be registered in the DI container or the Akka.NET actor system.
@@ -61,6 +61,7 @@ The Host must bind configuration sections from `appsettings.json` to strongly-ty
| `ScadaLink:Security` | `SecurityOptions` | Security & Auth | LdapServer, LdapPort, LdapUseTls, JwtSigningKey, JwtExpiryMinutes, IdleTimeoutMinutes |
| `ScadaLink:InboundApi` | `InboundApiOptions` | Inbound API | DefaultMethodTimeout |
| `ScadaLink:Notification` | `NotificationOptions` | Notification Service | (SMTP config is stored in config DB and deployed to sites, not in appsettings) |
| `ScadaLink:ManagementService` | `ManagementServiceOptions` | Management Service | (Reserved for future configuration) |
| `ScadaLink:Logging` | `LoggingOptions` | Host | Serilog sink configuration, log level overrides |
#### Convention
@@ -107,6 +108,10 @@ The Host must configure the Akka.NET actor system using Akka.Hosting with:
- **Split-Brain Resolver**: Configured with the strategy and stable-after duration from `ClusterConfiguration`.
- **Actor registration**: Each component's actors registered via its `AddXxxActors()` extension method, conditional on the node's role.
### REQ-HOST-6a: ClusterClientReceptionist (Central Only)
On central nodes, the Host must configure the Akka.NET **ClusterClientReceptionist** and register the ManagementActor with it. This allows external processes (e.g., the CLI) to discover and communicate with the ManagementActor via ClusterClient without joining the cluster as full members. The receptionist is started as part of the Akka.NET bootstrap (REQ-HOST-6) on central nodes only.
### REQ-HOST-7: ASP.NET Web Endpoints (Central Only)
On central nodes, the Host must use `WebApplication.CreateBuilder` to produce a full ASP.NET Core host with Kestrel, and must map web endpoints for:
@@ -140,7 +145,7 @@ Each component library must expose its services to the Host via a consistent set
- `AkkaConfigurationBuilder.AddXxxActors()` — registers the component's actors with the Akka.NET actor system (for components that have actors).
- `WebApplication.MapXxx()` — maps the component's web endpoints (only for CentralUI and InboundAPI).
The Host's `Program.cs` calls these extension methods; the component libraries own the registration logic. This keeps the Host thin and each component self-contained.
The Host's `Program.cs` calls these extension methods; the component libraries own the registration logic. This keeps the Host thin and each component self-contained. The ManagementService component additionally registers the ManagementActor with ClusterClientReceptionist in its `AddManagementServiceActors()` method.
---
@@ -158,6 +163,7 @@ The Host's `Program.cs` calls these extension methods; the component libraries o
| Security | Yes | No | Yes | Yes | No |
| CentralUI | Yes | No | Yes | No | Yes |
| InboundAPI | Yes | No | Yes | No | Yes |
| ManagementService | Yes | No | Yes | Yes | No |
| SiteRuntime | No | Yes | Yes | Yes | No |
| DataConnectionLayer | No | Yes | Yes | Yes | No |
| StoreAndForward | No | Yes | Yes | Yes | No |
@@ -168,7 +174,7 @@ The Host's `Program.cs` calls these extension methods; the component libraries o
## Dependencies
- **All 15 component libraries**: The Host references every component project to call their extension methods.
- **All 17 component libraries**: The Host references every component project to call their extension methods (excludes CLI, which is a separate executable).
- **Akka.Hosting**: For `AddAkka()` and the hosting configuration builder.
- **Akka.Remote.Hosting, Akka.Cluster.Hosting, Akka.Persistence.Hosting**: For Akka subsystem configuration.
- **Serilog.AspNetCore**: For structured logging integration.
@@ -181,4 +187,5 @@ The Host's `Program.cs` calls these extension methods; the component libraries o
- **Configuration Database**: The Host registers the DbContext and wires repository implementations to their interfaces. In development, triggers auto-migration; in production, validates schema version.
- **ClusterInfrastructure**: The Host configures the underlying Akka.NET cluster that ClusterInfrastructure manages at runtime.
- **CentralUI / InboundAPI**: The Host maps their web endpoints into the ASP.NET Core pipeline on central nodes.
- **ManagementService**: The Host registers the ManagementActor and configures ClusterClientReceptionist on central nodes, enabling CLI access.
- **HealthMonitoring**: The Host's startup validation and logging configuration provide the foundation for health reporting.