Audit Worker (apps/audit)

The Audit Worker (audit-worker) is a crucial backend component responsible for processing and storing audit log events. These events are generated by various services within the platform to track significant actions and changes.

Purpose

The primary purpose of the Audit Worker is to:

• Consume audit log events from a centralized Redis queue.
• Process these events, mapping them to a structured format.
• Persist the processed audit logs into a PostgreSQL database for long-term storage, analysis, and compliance purposes.

This ensures that a comprehensive trail of activities is maintained across the system.

Architecture

• Event Source: Services across the platform use the @repo/audit package to send audit events to a specific Redis queue.
• Queueing System: BullMQ, a robust Node.js library for message queues based on Redis, is used to manage the audit events.
• Worker Process: The audit-worker is a Node.js application that listens to this BullMQ queue.
• Data Processing: Upon receiving an event, the worker parses the data. It maps known event fields to dedicated columns in the audit_log database table. Any additional, service-specific properties are stored in a details JSONB column, allowing for flexibility in the audit data captured.
• Database: Processed audit events are stored in a PostgreSQL database. Drizzle ORM is used to interact with the database, managing schema and queries.
• Logging: The worker utilizes workers-tagged-logger for its operational logging, configurable via environment variables.
• Error Handling: BullMQ's built-in mechanisms handle job retries in case of processing failures.

Data Model

The core data is stored in an audit_log table (defined in apps/audit/src/db/schema.ts). Key fields typically include:

• id: Unique identifier for the audit log entry.
• timestamp: Time of the event.
• actor: Information about the user or system component that performed the action.
• action: The type of action performed (e.g., USER_LOGIN, PATIENT_RECORD_VIEWED, DATA_EXPORTED).
• target: Information about the entity or resource that was affected by the action.
• outcome: Result of the action (e.g., SUCCESS, FAILURE).
• details: A JSONB column to store any other relevant information specific to the event.

Configuration

The worker is configured primarily through environment variables:

• DATABASE_URL: Connection string for the PostgreSQL database.
• REDIS_URL: Connection string for the Redis instance.
• AUDIT_QUEUE_NAME: Name of the BullMQ queue to monitor (default: audit).
• LOG_LEVEL: Specifies the logging verbosity (e.g., info, debug).
• WORKER_CONCURRENCY: Defines how many jobs the worker can process concurrently.

How it Works

1. Connection: The worker establishes connections to Redis (for the queue) and PostgreSQL (for data storage).
2. Listening: It actively listens to the designated BullMQ queue for incoming jobs.
3. Job Consumption: When a new job (representing an AuditLogEvent) is picked up: a. The event data is parsed and validated. b. The data is mapped to the audit_log schema. c. The record is inserted into the PostgreSQL database using Drizzle ORM.
4. Acknowledgement: Upon successful insertion, the job is marked as complete in the queue. If an error occurs, BullMQ's retry strategy is invoked.

Importance for the Platform

The Audit Worker plays a vital role in:

• Security Monitoring: Detecting suspicious activities or unauthorized access attempts.
• Compliance: Meeting regulatory requirements for data access and modification tracking (e.g., HIPAA).
• Debugging and Troubleshooting: Providing a historical record of actions that can help diagnose issues.
• Analytics: Offering insights into system usage patterns.

For details on setting up and running the worker locally, refer to its own README.md in apps/audit/README.md. The primary focus here is its role and architecture within the overall system.