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.
This commit is contained in:
Joseph Doherty
@@ -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.
|
- Entity classes are persistence-ignorant POCOs in Commons; EF mappings in Configuration Database.
|
||||||
- Repository interfaces defined in Commons; implementations in Configuration Database.
|
- Repository interfaces defined in Commons; implementations in Configuration Database.
|
||||||
- EF Core migrations: auto-apply in dev, manual SQL scripts for production.
|
- 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`.
|
||||||
|
|||||||
@@ -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.
|
|
||||||
Reference in New Issue
Block a user