From 4ec5d5042577e141b755677e72415f94cac77d8f Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Mon, 16 Mar 2026 09:31:09 -0400
Subject: [PATCH] Add namespace and folder convention for Commons shared
 interfaces and types

Define REQ-COM-5b with full folder hierarchy, namespace rules, and naming
conventions for types, interfaces, entities, and message contracts. Organizes
by category (Types, Interfaces, Entities, Messages) and domain area within
each category.
---
 Component-Commons.md | 86 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/Component-Commons.md b/Component-Commons.md
index 4c841ee..1f1d35d 100644
--- a/Component-Commons.md
+++ b/Component-Commons.md
@@ -118,6 +118,92 @@ Since the system supports cross-site artifact version skew (sites may temporaril
 - Breaking changes require a new message type and a coordinated deployment to all nodes.
 - The Akka.NET serialization binding configuration (in the Host component) must explicitly map message types to serializers to prevent accidental binary serialization.
 
+### REQ-COM-5b: Namespace & Folder Convention
+
+All types in Commons are organized by **category** and **domain area** using a consistent namespace and folder hierarchy:
+
+```
+ScadaLink.Commons/
+├── Types/                          # REQ-COM-1: Shared data types
+│   ├── DataType.cs
+│   ├── RetryPolicy.cs
+│   ├── Result.cs
+│   └── Enums/
+│       ├── InstanceState.cs
+│       ├── DeploymentStatus.cs
+│       ├── AlarmState.cs
+│       ├── AlarmTriggerType.cs
+│       └── ConnectionHealth.cs
+├── Interfaces/                     # Shared interfaces by concern
+│   ├── Protocol/                   # REQ-COM-2: Protocol abstraction
+│   │   ├── IDataConnection.cs
+│   │   ├── TagValue.cs
+│   │   └── SubscriptionCallback.cs
+│   ├── Repositories/               # REQ-COM-4: Per-component repository interfaces
+│   │   ├── ITemplateEngineRepository.cs
+│   │   ├── IDeploymentManagerRepository.cs
+│   │   ├── ISecurityRepository.cs
+│   │   ├── IInboundApiRepository.cs
+│   │   ├── IExternalSystemRepository.cs
+│   │   ├── INotificationRepository.cs
+│   │   └── ICentralUiRepository.cs
+│   └── Services/                   # REQ-COM-4a: Cross-cutting service interfaces
+│       └── IAuditService.cs
+├── Entities/                       # REQ-COM-3: Domain entity POCOs, by domain area
+│   ├── Templates/
+│   │   ├── Template.cs
+│   │   ├── TemplateAttribute.cs
+│   │   ├── TemplateAlarm.cs
+│   │   ├── TemplateScript.cs
+│   │   └── TemplateComposition.cs
+│   ├── Instances/
+│   │   ├── Instance.cs
+│   │   ├── InstanceAttributeOverride.cs
+│   │   ├── InstanceConnectionBinding.cs
+│   │   └── Area.cs
+│   ├── Sites/
+│   │   ├── Site.cs
+│   │   ├── DataConnection.cs
+│   │   └── SiteDataConnectionAssignment.cs
+│   ├── ExternalSystems/
+│   │   ├── ExternalSystemDefinition.cs
+│   │   ├── ExternalSystemMethod.cs
+│   │   └── DatabaseConnectionDefinition.cs
+│   ├── Notifications/
+│   │   ├── NotificationList.cs
+│   │   ├── NotificationRecipient.cs
+│   │   └── SmtpConfiguration.cs
+│   ├── InboundApi/
+│   │   ├── ApiKey.cs
+│   │   └── ApiMethod.cs
+│   ├── Security/
+│   │   ├── LdapGroupMapping.cs
+│   │   └── SiteScopeRule.cs
+│   ├── Deployment/
+│   │   ├── DeploymentRecord.cs
+│   │   └── SystemArtifactDeploymentRecord.cs
+│   ├── Scripts/
+│   │   └── SharedScript.cs
+│   └── Audit/
+│       └── AuditLogEntry.cs
+└── Messages/                       # REQ-COM-5: Cross-component message contracts, by concern
+    ├── Deployment/
+    ├── Lifecycle/
+    ├── Health/
+    ├── Communication/
+    ├── Streaming/
+    ├── DebugView/
+    ├── ScriptExecution/
+    └── Artifacts/
+```
+
+**Naming rules**:
+- Namespaces mirror the folder structure: `ScadaLink.Commons.Entities.Templates`, `ScadaLink.Commons.Interfaces.Repositories`, etc.
+- Interface names use the `I` prefix: `ITemplateEngineRepository`, `IAuditService`, `IDataConnection`.
+- Entity classes are named after the domain concept (no suffixes like `Entity` or `Model`): `Template`, `Instance`, `Site`.
+- Message contracts are named as commands, events, or responses: `DeployInstanceCommand`, `DeploymentStatusResponse`, `AttributeValueChanged`.
+- Enums use singular names: `AlarmState`, not `AlarmStates`.
+
 ### REQ-COM-6: No Business Logic
 
 Commons must contain only: