Joseph Doherty
0974de1df5
CLAUDE.md points at .claude/skills/scadabridge-components/SKILL.md as the component catalog and .claude/skills/scadabridge-cluster-ops/SKILL.md as the source for the management URL, credentials and rebuild/redeploy commands — but neither file was tracked, so a fresh clone got instructions referencing content that was not there. Only the skill files are added; .claude/settings.local.json and scheduled_tasks.lock stay ignored via .gitignore as before.
40 lines
6.0 KiB
Markdown
40 lines
6.0 KiB
Markdown
---
|
||
name: scadabridge-components
|
||
description: Catalog of ScadaBridge's 27 components — what each one is and its key design commitments. Use when you need to know which component owns a concern, what a named component does, or how the component set fits together. Full per-component specs live in docs/requirements/Component-*.md; the README carries the component table.
|
||
---
|
||
|
||
# ScadaBridge Component Catalog
|
||
|
||
The authoritative spec for each entry is `docs/requirements/Component-<Name>.md`; this is the distilled index.
|
||
|
||
## Current Component List (27 components)
|
||
|
||
1. Template Engine — Template modeling, inheritance, composition, validation, flattening, diffs.
|
||
2. Deployment Manager — Central-side deployment pipeline, system-wide artifact deployment, instance lifecycle.
|
||
3. Site Runtime — Site-side actor hierarchy (Deployment Manager singleton, Instance/Script/Alarm Actors), script compilation, Akka stream.
|
||
4. Data Connection Layer — Protocol abstraction (OPC UA, custom), subscription management, clean data pipe.
|
||
5. Central–Site Communication — Akka.NET ClusterClient (command/control) + gRPC server-streaming (real-time data), message patterns, debug streaming.
|
||
6. Store-and-Forward Engine — Buffering, fixed-interval retry, parking, SQLite persistence, replication.
|
||
7. External System Gateway — External system definitions, API method invocation, database connections.
|
||
8. Notification Service — Central-only notification-list and SMTP definitions, per-type delivery adapters (sites no longer deliver notifications).
|
||
9. Central UI — Web-based management interface, all workflows.
|
||
10. Security & Auth — LDAP/AD authentication, role-based authorization, site-scoped permissions.
|
||
11. Health Monitoring — Site health metrics collection and central reporting.
|
||
12. Site Event Logging — Local operational event logs at sites with central query access.
|
||
13. Cluster Infrastructure — Akka.NET cluster setup, active/standby failover, singleton support.
|
||
14. Inbound API — Web API for external systems, API key auth, script-based implementations.
|
||
15. Host — Single deployable binary, role-based component registration, Akka.NET bootstrap.
|
||
16. Commons — Shared types, POCO entity classes, repository interfaces, message contracts.
|
||
17. Configuration Database — EF Core data access layer, repositories, unit-of-work, audit logging (IAuditService), migrations.
|
||
18. Management Service — Akka.NET actor providing programmatic access to all admin operations, ClusterClientReceptionist registration.
|
||
19. CLI — Command-line tool using HTTP Management API, System.CommandLine, JSON/table output.
|
||
20. Traefik Proxy — Reverse proxy/load balancer fronting central cluster, active node routing via `/health/active`, automatic failover.
|
||
21. Notification Outbox — Central component ingesting store-and-forwarded notifications, `Notifications` audit table, dispatcher loop, retry/parking, delivery KPIs.
|
||
22. Site Call Audit — Central component auditing site cached calls (`CachedCall`/`CachedWrite`); `SiteCalls` audit table, telemetry ingest, reconciliation, KPIs, central→site Retry/Discard relay; sites remain the source of truth.
|
||
23. Audit Log — Central append-only AuditLog table spanning every script-trust-boundary action (outbound API sync+cached, outbound DB sync+cached, notifications, inbound API). Site SQLite hot-path + gRPC telemetry + reconciliation; combined telemetry with Site Call Audit; central direct-write for Notification Outbox dispatch + Inbound API; monthly partitioning, 365-day retention.
|
||
24. Transport — File-based, encrypted bundle export/import via Central UI. Templates (with **all** child collections — attributes/alarms/scripts/compositions/**native-alarm-sources**, field-complete incl. `LockedInDerived` + script cadence/timeout), system artifacts, central-only configuration, plus site/instance-scoped config (`Site`s, site `DataConnection`s, `Instance`s + real `AreaName` by name) reconciled across environments by a `BundleNameMap` name-mapping subsystem. Per-conflict resolution with a per-line Myers diff. Runs the **script trust gate** at import review (5th `ScriptTrustValidator` call site — forbidden-API scripts rejected pre-runtime; covers template/shared/ApiMethod bodies, template script + alarm Expression-trigger bodies, **and instance alarm-override trigger expressions** — all hard-block; template-script name-resolution findings are advisory warnings, ApiMethod findings hard-block). Correlated audit via `BundleImportId`. Never touches site runtime nodes (imported instances land `NotDeployed`).
|
||
25. Script Analysis — Shared authoritative script-trust analyzer: unified forbidden-API deny-list (`ScriptTrustPolicy`), fused semantic+syntactic validator (`ScriptTrustValidator`), Roslyn compile wrapper (`RoslynScriptCompiler`), and compile-only globals stubs (`ScriptCompileSurface`/`TriggerCompileSurface`); consumed by Template Engine, Site Runtime, Inbound API, and Central UI.
|
||
26. KPI History — Reusable central KPI-history backbone: tall/EAV `KpiSample` store in central MS SQL, `KpiHistoryRecorderActor` cluster singleton (`kpi-history-recorder`, not readiness-gated) sampling DI-registered `IKpiSampleSource`s every minute, bucketed query (`GetRawSeriesAsync` + `KpiSeriesBucketer`) + scoped `KpiHistoryQueryService`, and a reusable custom-SVG `KpiTrendChart`; ships trends for Notification Outbox, Site Call Audit, Audit Log, and Site Health.
|
||
27. DelmiaNotifier — Standalone external client tool (NOT a cluster component, NOT in the Host): a compact Native-AOT (`win-x64`) console app (`WWNotifier.exe`) that DELMIA Apriso shells out to per recipe download. POSTs to the Inbound API `DelmiaRecipeDownload` method (`X-API-Key`, key from `SCADABRIDGE_API_KEY`), with connect-failure-only failover across a comma-list of base URLs, and reports the legacy `YES`/`NO` + exit-code stdout contract — a drop-in replacement for the legacy `WWNotifier` (see `docs/former-api-specs/dnc/`). Zero-dependency BCL-only, `System.Text.Json` source-gen. Project README: `src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier/README.md`; design: `docs/plans/2026-06-26-delmia-recipe-notifier-design.md`.
|
||
|