Audit Logging
Relevant source files
The following files were used as context for generating this wiki page:
Audit Logging in DRX CRM is a critical security and compliance system designed to ensure financial correctness and operational accountability. It provides an immutable, append-only record of all sensitive actions performed within the platform, including price overrides, inventory adjustments, and permission modifications. The system is architected to support multi-tenancy with strict isolation, ensuring that audit trails are secure and accessible only to authorized roles.
The audit logging framework serves as the source of truth for security audits, capturing the "who, what, and when" of every critical change. This system is essential for regulated small businesses that require inventory traceability and financial transparency.
Sources: testsprite_tests/standard_prd.json:6-10, README.md:23-23, scripts/help-center-data.ts:985-995
System Architecture
The Audit Logging system consists of three main layers: the data storage layer (PostgreSQL), the API layer for retrieval and filtering, and the Admin UI for visualization.
Data Flow and Immutability
Every sensitive action triggers a log entry that is stored in the system_audit_log table. These logs are designed to be immutable; the system does not allow deletion or modification of audit records once they are created.
The diagram above illustrates the path from a user action to the creation of a permanent record in the system audit log.
Sources: app/(app)/admin/audit/page.tsx:142-145, testsprite_tests/TC006_test_audit_log_generation_for_sensitive_actions.py:160-175, testsprite_tests/standard_prd.json:115-120
Audit Data Model
The primary data structure for audit tracking is the system_audit_log. It captures granular details about the actor, the target entity, and the specific changes made.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the audit entry |
created_at | Timestamp | Date and time the action occurred |
action | String | The type of action (e.g., price_override, void, inventory_adjustment) |
entity_type | String | The type of object affected (e.g., sale, user, inventory) |
entity_id | String | The specific ID of the target object |
user_id | String | The ID of the user (Actor) who performed the action |
business_id | UUID | The tenant ID for data isolation |
old_values | JSONB | State of the entity before the change |
new_values | JSONB | State of the entity after the change (or the request payload) |
Sources: app/(app)/admin/audit/page.tsx:88-95, app/(app)/admin/audit/page.tsx:210-250, testsprite_tests/standard_prd.json:130-155
Sensitive Actions Tracking
The system specifically targets actions that impact financial integrity, security, or inventory accuracy.
Financial and Inventory Actions
- Price Overrides: Logged during POS transactions when a supervisor or manager overrides a standard price.
- Voids and Refunds: Captures details when a sale is cancelled or returned, including reasons.
- Inventory Adjustments: Logs increases, decreases, or "set-to" corrections, requiring a reason for the change.
Governance and Security Actions
- Permission Changes: Tracks role assignments and modifications to prevent unauthorized elevation.
- RTBF Deletions: Records "Right to be Forgotten" actions where PII is masked for compliance.
Sources: testsprite_tests/TC006_test_audit_log_generation_for_sensitive_actions.py:44-145, testsprite_tests/testsprite_frontend_test_plan.json:230-265, scripts/help-center-data.ts:985-995
Audit Logs API
The Audit Logs API provides a secure interface for retrieving logs with support for tenant-based isolation and advanced filtering.
The sequence diagram shows the filtered retrieval process ensuring data is only accessed for the authorized tenant.
Sources: testsprite_tests/standard_prd.json:130-155, tests/integration/audit.test.ts:40-66
API Parameters
| Parameter | Location | Description |
|---|---|---|
business_id | Query | Filters logs by tenant ID (required for isolation) |
action | Query | Filters by specific action type (e.g., price_override) |
type | Query | Filters by target entity type |
date_range | Query | Filters logs within a specific time period |
Sources: testsprite_tests/standard_prd.json:140-155, tests/integration/audit.test.ts:58-65
Admin Interface
The Admin Console includes a dedicated "System Audit Trails" page (app/(app)/admin/audit/page.tsx) for security oversight.
Key Features
- Global Search: Allows searching by action, user ID, or entity type.
- Tenant Filtering: Admins can switch views between different business profiles.
- Payload Inspection: A "View Payload" feature allows expanding entries to see the full
old_valuesandnew_valuesJSON structures. - Export: Supports exporting filtered audit trails to CSV or JSON formats for external reporting.
Sources: app/(app)/admin/audit/page.tsx:142-200, app/(app)/admin/page.tsx:103-113
Summary
Audit Logging is a fundamental pillar of the DRX CRM architecture, enforcing accountability through immutable record-keeping. By capturing detailed payloads of sensitive financial and administrative actions, the system provides a robust trail for compliance and security forensics. The integration of tenant isolation at the API level ensures that while logs are exhaustive, they remain strictly confidential to the appropriate business entities.
Sources: testsprite_tests/standard_prd.json:25-35, scripts/help-center-data.ts:985-995