From f0108e161b1e87b9bd0984a3836e19f24011c432 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 16 Mar 2026 07:45:18 -0400 Subject: [PATCH] Housekeeping: remove stale AuditLogging component, add Codex MCP tool usage note Audit logging was absorbed into the Configuration Database component (IAuditService), making the separate Component-AuditLogging.md redundant. Also added tool usage guidance to CLAUDE.md for Codex MCP model selection. --- CLAUDE.md | 4 ++ Component-AuditLogging.md | 143 -------------------------------------- 2 files changed, 4 insertions(+), 143 deletions(-) delete mode 100644 Component-AuditLogging.md diff --git a/CLAUDE.md b/CLAUDE.md index e88974e..f87255d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,3 +77,7 @@ There is no source code in this project — only design documentation in markdow - Entity classes are persistence-ignorant POCOs in Commons; EF mappings in Configuration Database. - Repository interfaces defined in Commons; implementations in Configuration Database. - EF Core migrations: auto-apply in dev, manual SQL scripts for production. + +## Tool Usage + +- When consulting with the Codex MCP tool, use model `gpt-5.4`. diff --git a/Component-AuditLogging.md b/Component-AuditLogging.md deleted file mode 100644 index b0e903a..0000000 --- a/Component-AuditLogging.md +++ /dev/null @@ -1,143 +0,0 @@ -# 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.