Initial design docs from claude.ai refinement sessions

Component-NotificationService.md

@@ -0,0 +1,59 @@
+# Component: Notification Service
+
+## Purpose
+
+The Notification Service provides email notification capabilities to scripts running at site clusters. It manages notification lists, handles email delivery, and integrates with the Store-and-Forward Engine for reliable delivery when the email server is unavailable.
+
+## Location
+
+Central cluster (definition management). Site clusters (email delivery).
+
+## Responsibilities
+
+### Definitions (Central)
+- Store notification lists in the configuration database: list name, recipients (name + email address).
+- Store email server configuration (SMTP settings).
+- Deploy notification lists and SMTP configuration uniformly to all sites. Deployment requires **explicit action** by a user with the Deployment role.
+- Managed by users with the Design role.
+
+### Delivery (Site)
+- Resolve notification list names to recipient lists.
+- Compose and send emails via SMTP.
+- On delivery failure, submit the notification to the Store-and-Forward Engine for buffered retry.
+
+## Notification List Definition
+
+Each notification list includes:
+- **Name**: Unique identifier (e.g., "Maintenance-Team", "Shift-Supervisors").
+- **Recipients**: One or more entries, each with:
+  - Recipient name.
+  - Email address.
+
+## Email Server Configuration
+
+- SMTP server address, port, authentication credentials, TLS settings.
+- Retry settings: Max retry count, fixed time between retries (used by Store-and-Forward Engine).
+- Defined centrally, deployed to all sites.
+
+## Script API
+
+```csharp
+Notify.To("listName").Send("subject", "message")
+```
+
+- Available to instance scripts (via Script Execution Actors), alarm on-trigger scripts (via Alarm Execution Actors), and shared scripts (executing inline).
+- Resolves the list name to recipients, composes the email, and attempts delivery.
+- On failure, the notification is handed to the Store-and-Forward Engine.
+
+## Dependencies
+
+- **Configuration Database (MS SQL)**: Stores notification list definitions and SMTP config.
+- **Store-and-Forward Engine**: Handles buffering for failed email deliveries.
+- **Security & Auth**: Design role manages notification lists.
+- **Configuration Database (via IAuditService)**: Notification list changes are audit logged.
+
+## Interactions
+
+- **Site Runtime (Script/Alarm Execution Actors)**: Scripts invoke `Notify.To().Send()` through this component.
+- **Store-and-Forward Engine**: Failed notifications are buffered here.
+- **Deployment Manager**: Receives updated notification lists and SMTP config as part of system-wide artifact deployment (triggered explicitly by Deployment role).