dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial design docs from claude.ai refinement sessions

Browse Source
This commit is contained in:
Joseph Doherty
2026-03-16 07:39:26 -04:00
commit 1944f94fed
22 changed files with 2821 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
Component-AuditLogging.md Normal file
View File

@@ -0,0 +1,143 @@
# Component: Audit Logging
## Purpose
The Audit Logging component records all configuration and administrative changes in the system with the resulting state after each change, providing a queryable trail of who changed what and when.
## Location
Central cluster. All auditable actions occur through central (sites receive configurations but do not originate changes).
## Responsibilities
- Provide a service interface (`IAuditService`) for components to log changes after successful operations.
- Serialize entity state as JSON and store audit entries in the configuration MS SQL database.
- Write audit entries synchronously within the same database transaction as the change (via the unit-of-work).
- Provide query capabilities for the Central UI audit log viewer.
---
## Integration Pattern
Audit logging uses a **direct service call** pattern. Components call `IAuditService` after a successful operation:
```
IAuditService.LogAsync(user, action, entityType, entityId, entityName, afterState)
```
- **`user`**: The authenticated AD user who performed the action (provided by Security & Auth).
- **`action`**: The type of operation (create, update, delete, deploy, disable, enable).
- **`entityType`**: What was changed (template, instance, alarm, shared script, etc.).
- **`entityId`**: Unique identifier of the specific entity.
- **`entityName`**: Human-readable name of the entity.
- **`afterState`**: The entity's state after the change, serialized as JSON. Null for deletes.
The `IAuditService` interface is defined in **Commons** (alongside the other shared interfaces). The implementation is provided by the Audit Logging component and registered in the DI container.
### Transactional Guarantee
Audit entries are written **synchronously** within the same database transaction as the change. Since all central components use the unit-of-work pattern (EF Core's DbContext), the audit entry is added to the same DbContext and committed in the same `SaveChangesAsync()` call. This guarantees:
- If the change succeeds, the audit entry is always recorded.
- If the change fails and rolls back, the audit entry is also rolled back.
- No audit entries are lost due to process crashes between the change and the audit write.
### Integration Example
```
Template Engine: Update Template
│
├── repository.UpdateTemplate(template)
├── auditService.LogAsync(user, "update", "Template", template.Id,
│ template.Name, serialize(template))
└── repository.SaveChangesAsync() ← both the change and audit entry commit together
```
---
## Audited Actions
| Category | Actions |
|----------|---------|
| Templates | Create, edit, delete templates |
| Scripts | Create, edit, delete template scripts and shared scripts |
| Alarms | Create, edit, delete alarm definitions |
| Instances | Create, override values, bind connections, area assignment, disable, enable, delete |
| Deployments | Deploy to instance (who, what, which instance, success/failure) |
| System-Wide Artifact Deployments | Deploy shared scripts / external system definitions / DB connections / notification lists to sites (who, what, result) |
| External Systems | Create, edit, delete definitions |
| Database Connections | Create, edit, delete definitions |
| Notification Lists | Create, edit, delete lists and recipients |
| Inbound API | API key create, enable/disable, delete. API method create, edit, delete |
| Areas | Create, edit, delete area definitions |
| Sites & Data Connections | Create, edit, delete sites. Define and assign data connections to sites |
| Security/Admin | Role mapping changes, site permission changes |
---
## Audit Entry Schema
Each audit log entry contains:
| Field | Type | Description |
|-------|------|-------------|
| **Id** | Long / GUID | Unique identifier for the audit entry. |
| **Timestamp** | DateTimeOffset | When the action occurred (UTC). |
| **User** | String | Authenticated AD username who performed the action. |
| **Action** | String (enum) | The type of operation: `Create`, `Update`, `Delete`, `Deploy`, `Disable`, `Enable`. |
| **EntityType** | String | What was changed: `Template`, `Instance`, `SharedScript`, `Alarm`, `ExternalSystem`, `DatabaseConnection`, `NotificationList`, `ApiKey`, `ApiMethod`, `Area`, `Site`, `DataConnection`, `LdapGroupMapping`. |
| **EntityId** | String | Unique identifier of the specific entity. |
| **EntityName** | String | Human-readable name of the entity (for display without needing to deserialize state). |
| **State** | JSON (nvarchar(max)) | The entity's state after the change, serialized as JSON. Null for deletes. |
### State Serialization
- Entity state is serialized as **JSON** using the standard .NET JSON serializer.
- JSON is stored in an `nvarchar(max)` column in SQL Server.
- The UI can render the JSON state for inspection. SQL Server's built-in JSON functions (`JSON_VALUE`, `OPENJSON`) can be used for ad-hoc queries against the state if needed.
- For delete operations, the state is **null** (the entity no longer exists). The previous state can be found by querying the most recent prior audit entry for the same entity.
### Granularity
- **One audit entry per save operation**. When a user edits a template and changes multiple attributes in a single save, one audit entry is created containing the full template state after the save.
- This captures the complete picture of what the entity looked like after each change without requiring per-field tracking.
### Reconstructing Change History
Since only the "after" state is stored, a full change history for an entity can be reconstructed by querying all audit entries for that entity ordered by timestamp. Comparing consecutive entries (entry N-1's state vs. entry N's state) reveals what changed at each step. This is a query-time concern handled by the Central UI, not a write-time concern.
---
## Storage
- Stored in the **configuration MS SQL database** in a dedicated audit table, accessed via the `IAuditLoggingRepository`.
- Entries are **append-only** — audit records are never modified or deleted.
- No retention policy — audit logs are retained **indefinitely**.
- Indexes on: `Timestamp`, `User`, `EntityType`, `EntityId`, `Action` for efficient filtering.
---
## Query Capabilities
The Central UI audit log viewer can filter by:
- **User**: Who made the change.
- **Entity type**: What kind of entity was changed.
- **Action type**: What kind of operation was performed.
- **Time range**: When the change occurred.
- **Specific entity ID/name**: Changes to a particular entity.
Results are returned in reverse chronological order (most recent first) with pagination support.
---
## Dependencies
- **Configuration Database**: Storage for audit entries via `IAuditLoggingRepository`. Audit entries participate in the same unit-of-work transaction as the changes they record.
- **Security & Auth**: Provides the authenticated user identity for each entry.
- **Commons**: Defines the `IAuditService` interface and `AuditLogEntry` entity class.
## Interactions
- **All central components that modify state**: Call `IAuditService.LogAsync()` after successful operations. This includes Template Engine, Deployment Manager, Security & Auth, Inbound API, External System Gateway, and Notification Service.
- **Central UI**: Provides the audit log viewer for querying and displaying entries.
- **Configuration Database**: Audit entries are committed in the same transaction as the changes they record.