Skip to content

AuditHandler

Publisher Platform Audit Trail Microservice

Service Type: Kubernetes Microservice
Technology: Node.js (JavaScript)
Runtime: Node.js Container
Last Updated: 2025-07-01

📋 Overview

The AuditHandler microservice is a critical component of the Publisher platform that creates comprehensive audit trails for all data changes. It processes document change events and generates detailed audit records using JSON patch operations to track what changed, when, and by whom. The service ensures compliance and provides complete traceability for all system modifications.

Key Features

  • JSON Patch-Based Auditing: Uses RFC 6902 JSON Patch to track precise changes
  • Multi-Collection Support: Handles auditing for various document types (campaigns, vendors, controls)
  • System Event Integration: Triggers system events for critical changes (e.g., control modifications)
  • Dual Output Streams: Sends audit records and system events to separate Event Hubs
  • Change Detection: Intelligent comparison between old and new record states
  • User Attribution: Tracks user information for all changes

🛠 Technology Stack

Component Technology
Language JavaScript (Node.js)
Runtime Node.js Container
Framework Express.js / HTTP Server
JSON Patch fast-json-patch
Messaging Azure Event Hub
Build Tool Webpack
Container Docker
Orchestration Kubernetes

🏗 Architecture

Service Architecture

  • Deployment Pattern: Kubernetes Deployment with HTTP Service
  • Input: HTTP POST requests with document change events
  • Output Streams:
  • audit Event Hub for audit records
  • publishersystemevents Event Hub for system events
  • Configuration: ConfigMap and environment variables
  • Monitoring: Application Insights integration

System Flow

graph TD
    A[Document Change Event] --> B[AuditHandler Microservice]
    B --> C[Message Validation]
    C --> D[Filter Object Properties]
    D --> E[Generate JSON Patches]
    E --> F[Create Audit Records]
    F --> G[Send to Audit Event Hub]
    G --> H{Collection = Controls?}
    H -->|Yes| I[Generate System Event]
    H -->|No| J[Complete Processing]
    I --> K[Send to System Events Hub]
    K --> J

🔄 Processing Pipeline

The AuditHandler follows a sophisticated audit processing pipeline:

Audit Processing Flow

graph LR
    A[Document Event] --> B[Property Filtering]
    B --> C[JSON Patch Generation]
    C --> D[Audit Record Creation]
    D --> E[Event Hub Publishing]
    E --> F[System Event Trigger]

Change Detection Logic

graph TD
    A[Input Message] --> B{Has Old & New Record?}
    B -->|Yes| C[JSON Patch Compare]
    B -->|No| D{Has New Record Only?}
    D -->|Yes| E[Generate Insert Patches]
    D -->|No| F[Generate Delete Patches]
    C --> G[Create Audit Records]
    E --> G
    F --> G

📡 API Specification

HTTP API Endpoint

  • Method: POST
  • Authentication: Internal service authentication
  • Content-Type: application/json
  • Port: 8080 (configurable)

Request Format

{
  "recordid": "unique-record-id",
  "ts": 1640995200000,
  "collection": "campaigns",
  "action": "update",
  "organizationId": "vendor-123",
  "auth": {
    "name": "user@example.com"
  },
  "record": {
    "id": "campaign-456",
    "friendlyName": "Updated Campaign",
    "partitionKey": "partition-123",
    "campaignId": "campaign-456"
  },
  "oldRecord": {
    "id": "campaign-456",
    "friendlyName": "Original Campaign",
    "partitionKey": "partition-123",
    "campaignId": "campaign-456"
  }
}

Response Format

{
  "statusCode": 200,
  "data": {
    // Original message data
  }
}

🔧 Business Logic

Audit Record Structure

Each audit record contains: - recordId: Unique identifier for the audit record - documentEventRecordId: Reference to the original document event - timestamp: When the change occurred - user: Who made the change - vendorId: Organization/vendor context - collection: Type of document changed - path: Specific field that changed - CRUD: Operation type (insert/update/delete) - which: Friendly name of the changed entity - campaignId: Campaign context (if applicable) - change: Details of what changed

Special Collection Handling

Controls Collection

When changes occur to the controls collection: 1. System Event Generation: Triggers ControlsChanged system event 2. Alert Integration: Sends event to AlertHandler for potential notifications 3. Enhanced Context: Includes full control object in system event

Campaigns Collection

  • Campaign ID Mapping: Uses record ID as campaign ID
  • Partition Key Handling: Manages campaign-specific partitioning

Vendors Collection

  • Vendor ID Mapping: Uses record ID as vendor ID
  • Organization Context: Maintains vendor-specific audit trails

JSON Patch Operations

sequenceDiagram
    participant DE as Document Event
    participant AH as AuditHandler
    participant JP as JSON Patch
    participant EH as Event Hub

    DE->>AH: Document Change Event
    AH->>AH: Filter Properties
    AH->>JP: Compare Old vs New
    JP-->>AH: Patch Operations
    AH->>AH: Create Audit Records
    AH->>EH: Publish Audit Records
    AH->>EH: Publish System Events (if controls)

⚙️ Configuration

Environment Variables

  • Event Hub connection strings
  • Application Insights connection string
  • Debug logging configuration
  • Timeout settings

Key Configuration Files

  • config/config.js: Main configuration
  • config/config.int.js: Integration environment
  • config/config.prod.js: Production environment
  • config/function.json: Service bindings configuration

Event Hub Configuration

{
  "audits": {
    "eventHubName": "audit",
    "direction": "out"
  },
  "systemevents": {
    "eventHubName": "publishersystemevents", 
    "direction": "out"
  }
}

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=audithandler

# View logs
kubectl logs -l app=audithandler -f

Local Development

# Install dependencies
npm install

# Run tests
npm test

# Start service
npm start

📊 Monitoring & Health Checks

Health Endpoints

  • Liveness: /live - Basic health check
  • Readiness: /ready - Service readiness check

Key Metrics to Monitor

  • Audit record processing rate
  • JSON patch generation success rate
  • Event Hub publishing success rate
  • System event trigger frequency
  • Processing latency per collection type

Logging

  • Debug Logging: Configurable debug levels
  • Error Tracking: Failed processing events
  • Performance Metrics: Processing time per audit record

🔧 Troubleshooting

Common Issues

Missing Audit Records

  1. Check Event Hub connectivity for audit stream
  2. Verify document event format matches expected schema
  3. Ensure proper authentication context in events

System Events Not Triggering

  1. Verify collection name is exactly controls (case-sensitive)
  2. Check Event Hub connectivity for publishersystemevents
  3. Validate partition key presence in control records

JSON Patch Generation Failures

# Check for malformed record structures
# Verify old/new record format consistency
# Review property filtering logic

🧪 Testing

Unit Tests

npm test

Manual Testing

Send test document change events and verify: 1. Audit records are created in Event Hub 2. System events trigger for control changes 3. JSON patches accurately reflect changes

🤝 Dependencies

Internal Dependencies

  • Document CRUD Services: Source of document change events
  • Event Hub Infrastructure: For audit record and system event publishing
  • Shared Node Modules: Logger utilities

External Dependencies

  • fast-json-patch: JSON patch generation and comparison
  • idgen: Unique ID generation
  • http-errors: HTTP error handling
  • jsonpath-plus: JSON path operations

This documentation was created through manual code analysis of the AuditHandler microservice codebase.