Audit Logging System
Relevant source files
The following files were used as context for generating this wiki page:
The Audit Logging System provides an append-only trail of activities within the Digital Healthcare Platform. It records administrative and clinical actions to ensure accountability and compliance with healthcare safety rules. The system is integrated with the platform's multi-tenancy architecture, ensuring that audit data is isolated by organization and accessible only to authorized personnel.
Sources: README.md:16-16, packages/db/prisma/schema.prisma:698-698
System Architecture
The audit system utilizes a dedicated audit_logs table in the PostgreSQL database. To maintain the integrity of the trail, database triggers block all update and delete operations on this table. Multi-tenancy is enforced through Postgres Row-Level Security (RLS), which ensures that staff members only access logs belonging to their organization.
Sources: packages/db/prisma/schema.prisma:415-415, packages/db/prisma/schema.prisma:698-698
Data Model
The AuditLog model captures the identity of the actor, the specific action performed, the entity affected, and technical metadata about the request.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the log entry. |
organisationId | UUID | ID of the tenant organization (nullable for platform-level logs). |
actorUserId | UUID | ID of the user who performed the action. |
action | String | Descriptor of the event (e.g., patient.updated). |
entityType | String | Type of resource affected (e.g., Patient). |
entityId | String | Unique ID of the affected resource. |
requestId | String | Trace ID associated with the API request. |
ip | String | Source IP address of the request. |
userAgent | String | Browser or client identification string. |
metadata | Json | Context-specific details (e.g., changed field names). |
at | DateTime | Timestamp of the event in UTC. |
Sources: packages/db/prisma/schema.prisma:699-712
Entity Relationships
The diagram below illustrates how audit logs relate to the broader system entities while maintaining a flat structure for append-only performance.
The AuditLog table maintains references to organizations and users but functions as a standalone historical record. Sources: packages/db/prisma/schema.prisma:699-713
Audited Actions
The system captures events across administrative and clinical modules. Metadata is used to store context without compromising sensitive data; for example, updates record which fields changed but not the actual values.
Clinical and Patient Events
- Patient Management: Registration (
patient.created), demographic updates (patient.updated), and changes to patient labels (patient.tags.changed). - Clinical Records: Viewing or saving consultation notes (
consultation.viewed,consultation.saved). - Medical Charts: Modifications to patient charts, including adding or removing allergies, conditions, and medications.
Sources: apps/api/test/patients.int.test.ts:79-82, apps/api/test/patients.int.test.ts:145-147, apps/api/test/clinical.int.test.ts:114-118, apps/api/test/clinical.int.test.ts:251-255
Action Data Flow
The following sequence shows how a patient update triggers an audit entry.
Audit entries are created as side effects of resource mutations within the API layer. Sources: apps/api/test/patients.int.test.ts:137-147, packages/contracts/src/openapi.ts:167-173
API Access
Audit logs are exposed via a secured REST endpoint. Access is restricted to users with the clinic_admin role.
Retrieve Audit Logs
GET /v1/audit-log
This endpoint returns a paginated list of logs for the caller's organization, sorted by timestamp in descending order.
Parameters:
limit: Integer (1-100, default 50).cursor: Base64 encoded UUID of the last record for pagination.
Sources: apps/api/src/modules/audit/routes.ts:14-25, packages/contracts/src/openapi.ts:544-550
Access to audit data requires both valid authentication and the specific clinic_admin role. Sources: apps/api/src/modules/audit/routes.ts:16-17, packages/db/prisma/schema.prisma:415-419
Implementation Details
Append-Only Enforcement
The system ensures historical integrity by preventing modifications. Prisma schema documentation indicates that updates and deletes are blocked by a trigger at the database level.
Sources: packages/db/prisma/schema.prisma:415-415
Metadata Privacy
To comply with security requirements (e.g., preventing sensitive data leakage in logs), the system records specific field names modified during an update but avoids recording the values themselves.
// Example audit entry metadata for a patient update
{
"fields": ["email", "address", "bloodGroup"]
}
Sources: apps/api/test/patients.int.test.ts:146-147, apps/api/test/clinical.int.test.ts:118-118
Pagination Logic
The API uses cursor-based pagination. The cursor is generated by encoding the id of the last row in the current page into a base64url string.
Sources: apps/api/src/modules/audit/routes.ts:20-43
Conclusion
The Audit Logging System is a core foundational component of the Digital Healthcare Platform. It provides a robust, tenant-isolated, and immutable record of all significant actions. By combining database-level protections with strict role-based access control, the system maintains a high standard of data integrity and security for clinic operations.