lmxopcua/docs/reqs/GalaxyRepositoryReqs.md

Galaxy Repository — Component Requirements

Parent: HLR-002, HLR-005

GR-001: Hierarchy Extraction

The system shall query the Galaxy Repository database to extract all deployed objects with their parent-child containment relationships, contained names, and tag names.

Acceptance Criteria

• Executes queries/hierarchy.sql against the ZB database.
• Returns a list of objects with: gobject_id, tag_name, contained_name, browse_name, parent_gobject_id, is_area.
• Objects with parent_gobject_id = 0 are children of the root ZB node.
• Only deployed, non-template objects matching the category filter (areas, engines, user-defined objects, etc.) are returned.
• Query completes within 10 seconds on a typical Galaxy (hundreds of objects). Log a Warning if it takes longer.

Details

• Results are ordered by parent_gobject_id, tag_name for deterministic tree building.
• If the query returns zero rows, log a Warning (Galaxy may have no deployed objects, or the DB connection may be misconfigured).
• Orphan detection: if a row references a parent_gobject_id that does not exist in the result set and is not 0, log a Warning and skip that node.

---

GR-002: Attribute Extraction

The system shall query user-defined (dynamic) attributes for deployed objects, including data type, array flag, and array dimensions.

Acceptance Criteria

• Executes queries/attributes.sql using the template chain CTE to resolve inherited attributes.
• Returns: gobject_id, tag_name, attribute_name, full_tag_reference, mx_data_type, is_array, array_dimension, security_classification.
• Attributes starting with _ are filtered out by the query.
• array_dimension is correctly extracted from the mx_value hex bytes (positions 13-16, little-endian uint16).

Details

• CTE recursion depth is limited to 10 levels (per the query). This is sufficient for Galaxy template hierarchies.
• If mx_data_type is null or not in the known set (1-8, 13-16), default to String.
• If gobject_id from an attribute row does not match any hierarchy object, skip that attribute (object may not be deployed).

---

GR-003: Change Detection

The system shall poll galaxy.time_of_last_deploy at a configurable interval to detect when a new deployment has occurred.

Acceptance Criteria

• Polls SELECT time_of_last_deploy FROM galaxy at a configurable interval (GalaxyRepository:ChangeDetectionIntervalSeconds, default 30 seconds).
• Compares the returned timestamp to the last known value stored in memory.
• If different, triggers a rebuild (re-run hierarchy + attributes queries, notify OPC UA server).
• First poll after startup always triggers an initial build.
• If the query fails (SQL timeout, connection error), log Warning and retry at next interval. Do not trigger a rebuild on failure.

Details

• Polling runs on a background timer thread, not blocking the STA thread.
• time_of_last_deploy is a datetime column. Compare using exact equality (not range).

---

GR-004: Rebuild on Change

When a deployment change is detected, the system shall re-query hierarchy and attributes and provide the updated structure to the OPC UA server for address space rebuild.

Acceptance Criteria

• On change detection, re-query both hierarchy and attributes.
• Provide the new data set to the OPC UA server component for address space replacement.
• Log at Information level: "Galaxy deployment change detected. Rebuilding address space. ({ObjectCount} objects, {AttributeCount} attributes)".
• Log total rebuild time at Information level.
• If the re-query fails, log Error and keep the existing address space (do not clear it).

Details

• Rebuild is not atomic from the DB perspective — hierarchy and attributes are two separate queries. This is acceptable; deployment is an infrequent operation.
• Raise an event/callback that the OPC UA server subscribes to: OnGalaxyChanged(hierarchyData, attributeData).

---

GR-005: Connection Configuration

Database connection parameters shall be configurable via appsettings.json (connection string using Windows Authentication by default).

Acceptance Criteria

• Connection string in appsettings.json under GalaxyRepository:ConnectionString.
• Default: Server=localhost;Database=ZB;Integrated Security=true (Windows Auth).
• ADO.NET SqlConnection used for queries (.NET Framework 4.8 built-in).
• Connection is opened per-query (not kept open). Connection pooling handles efficiency.
• If the initial connection test at startup fails, log Error with the connection string and continue attempting (change detection polls will keep retrying).

Details

• Command timeout: configurable via GalaxyRepository:CommandTimeoutSeconds, default 30 seconds.
• No ORM. Raw ADO.NET with SqlCommand and SqlDataReader. SQL text is embedded as constants (not dynamically constructed).

---

GR-006: Query Safety

All SQL queries shall be static read-only SELECT statements. No writes to the Galaxy Repository database.

Acceptance Criteria

• All queries are hardcoded SQL strings with no string concatenation or user-supplied parameters.
• No INSERT, UPDATE, DELETE, or DDL statements are ever executed against the Galaxy database.
• Queries use only SELECT with read-only intent.

---

GR-007: Startup Validation

On startup, the Galaxy Repository component shall validate database connectivity.

Acceptance Criteria

• Execute a simple test query (SELECT 1) against the configured database.
• If the database is unreachable, log an Error but do not prevent service startup.
• The service runs in degraded mode (empty address space) until the database becomes available and the next change detection poll succeeds.