Initial design docs from claude.ai refinement sessions

Component-DataConnectionLayer.md

@@ -0,0 +1,80 @@
+# Component: Data Connection Layer
+
+## Purpose
+
+The Data Connection Layer provides a uniform interface for reading from and writing to physical machines at site clusters. It abstracts protocol-specific details behind a common interface, manages subscriptions, and delivers live tag value updates to Instance Actors. It is a **clean data pipe** — it performs no evaluation of triggers, alarm conditions, or business logic.
+
+## Location
+
+Site clusters only. Central does not interact with machines directly.
+
+## Responsibilities
+
+- Manage data connections defined at the site level (OPC UA servers, custom protocol endpoints).
+- Establish and maintain connections to data sources based on deployed instance configurations.
+- Subscribe to tag paths as requested by Instance Actors (based on attribute data source references in the flattened configuration).
+- Deliver tag value updates to the requesting Instance Actors.
+- Support writing values to machines (when Instance Actors forward `SetAttribute` write requests for data-connected attributes).
+- Report data connection health status to the Health Monitoring component.
+
+## Common Interface
+
+Both OPC UA and the custom protocol implement the same interface:
+
+```
+IDataConnection
+├── Connect(connectionDetails) → void
+├── Disconnect() → void
+├── Subscribe(tagPath, callback) → subscriptionId
+├── Unsubscribe(subscriptionId) → void
+├── Read(tagPath) → value
+├── Write(tagPath, value) → void
+└── Status → ConnectionHealth
+```
+
+Additional protocols can be added by implementing this interface.
+
+## Supported Protocols
+
+### OPC UA
+- Standard OPC UA client implementation.
+- Supports subscriptions (monitored items) and read/write operations.
+
+### Custom Protocol
+- Proprietary protocol adapter.
+- Implements the same subscription-based model as OPC UA.
+
+## Subscription Management
+
+- When an Instance Actor is created (as part of the Site Runtime actor hierarchy), it registers its data source references with the Data Connection Layer.
+- The DCL subscribes to the tag paths using the concrete connection details from the flattened configuration.
+- Tag value updates are delivered directly to the requesting Instance Actor.
+- When an Instance Actor is stopped (due to disable, delete, or redeployment), the DCL cleans up the associated subscriptions.
+- When a new Instance Actor is created for a redeployment, subscriptions are established fresh based on the new configuration.
+
+## Write-Back Support
+
+- When a script calls `Instance.SetAttribute` for an attribute with a data source reference, the Instance Actor sends a write request to the DCL.
+- The DCL writes the value to the physical device via the appropriate protocol.
+- The existing subscription picks up the confirmed new value from the device and delivers it back to the Instance Actor as a standard value update.
+- The Instance Actor's in-memory value is **not** updated until the device confirms the write.
+
+## Value Update Message Format
+
+Each value update delivered to an Instance Actor includes:
+- **Tag path**: The relative path of the attribute's data source reference.
+- **Value**: The new value from the device.
+- **Quality**: Data quality indicator (good, bad, uncertain).
+- **Timestamp**: When the value was read from the device.
+
+## Dependencies
+
+- **Site Runtime (Instance Actors)**: Receives subscription registrations and delivers value updates. Receives write requests.
+- **Health Monitoring**: Reports connection status.
+- **Site Event Logging**: Logs connection status changes.
+
+## Interactions
+
+- **Site Runtime (Instance Actors)**: Bidirectional — delivers value updates, receives subscription registrations and write-back commands.
+- **Health Monitoring**: Reports connection health periodically.
+- **Site Event Logging**: Logs connection/disconnection events.