Audit Trail - Enterprise Operations

Overview

Every meaningful action taken in the Compliance module is recorded in the Audit Trail. Each entry captures who did what, when, from which IP address, and what changed — making it possible to reconstruct the complete history of any document or approval request.

Advanced Filtering

Filter by date range, username, action type, and module. Combine multiple filters to zero in on exactly what you need.

CSV & JSON Export

Download the current filtered result set as CSV (for spreadsheet analysis) or JSON (for programmatic processing). Generated in the browser — no server round-trip.

Before / After Diff

For update actions, the entry detail panel shows the exact JSON fields that changed — old value on the left, new value on the right.

Paginated Results

Results are paginated at 50 per page with Previous / Next navigation. The entry count above the table always reflects the filtered total.

Tracked Action Types

Action	Badge colour	Triggered by
create	● Emerald	A new document or workflow is created.
update	● Sky	Document metadata, version, or status is changed.
delete	● Red	A document is archived (soft delete).
view	● Indigo	A user opens the document viewer modal.
download	● Violet	A user downloads a document file.
approve	● Emerald	An approval step is approved.
reject	● Amber	An approval step is rejected.
submit	● Sky	A document is submitted for approval.
acknowledge	● Teal	A user acknowledges a document version.
renew	● Sky	A document's review clock is reset from the Expiry Reminders screen (advances `nextReviewDate`, updates status).
login	● Emerald	User logs in to the application.
logout	● Slate	User logs out of the application.

Filter Controls

The filter bar sits above the table. All filters update the table live; the entry count above the table reflects the match count after all filters are applied.

Filter	Input type	How it works
Username search	Text input	Case-insensitive substring match on the `username` field. Enter a partial name to find all entries for that user.
Start date	Date picker	Shows entries on or after midnight of the selected date.
End date	Date picker	Shows entries on or before 23:59:59 of the selected date.
Action type	Dropdown	Exact match on the `action` field. Select "All Actions" to clear.
Module	Dropdown	Exact match on the `module` field (e.g. `compliance`, `hr`). Select "All Modules" to clear.

Combining filters

All filters are additive (AND logic). To find all approvals by a specific person in a date range, set Username = their name, Action = approve, and the start/end dates. The table updates immediately.

Entry Detail Panel

Click the eye icon on any row to open the full detail panel for that entry. The panel shows:

Timestamp — full date and time in the user's locale.
Username — the actor's login name (monospaced font).
Module and Entity type — e.g. compliance / document.
Entity ID — the internal ID of the affected record (useful for cross-referencing).
IP Address and Session ID — for security investigations.
User Agent — browser and OS string of the actor's device.

Before / After diff

For update and approve/reject entries, the panel shows a side-by-side diff:

Before (red tint) — JSON snapshot of the fields before the change.
After (green tint) — JSON snapshot of the fields after the change.

This makes it trivial to answer questions like "What was the document status before this approval?" or "Which metadata field changed in that update?"

Exporting the Audit Log

Click Export in the page header to open the export modal. The export covers the currently filtered set of entries — apply filters first to narrow scope, then export.

CSV format

The CSV includes these columns: Timestamp, Username, Action, Module, Entity Type, Entity Name, Entity ID, IP Address. The file is named audit-trail-YYYY-MM-DD.csv.

JSON format

The JSON export is the raw array of matching AuditLogEntry objects — all fields including oldValue, newValue, and userAgent. The file is named audit-trail-YYYY-MM-DD.json.

Export is browser-side — no server required

The export file is generated entirely in the browser from the already-loaded data. For very large date ranges, apply tighter filters before exporting to keep the file manageable. The maximum in-memory cap is 5,000 entries; if your log grows beyond that, earlier entries are discarded — schedule regular exports and archive them externally.

Log Retention & Integrity

Property	Value	Notes
In-memory cap	5,000 entries	Oldest entries are dropped when the cap is exceeded. Export regularly for long-term retention.
Storage file	`data/tenants/{tenantId}/compliance-audit.json`	Tenant-scoped, append-only array. Never edited by the application — only prepended.
Write timing	Synchronous on action	Every action writes immediately. No queuing in the current implementation.
Tamper detection	Planned	A hash-chain integrity check can be added per the Functional Requirements spec. Each entry stores a SHA-256 of its content; a verify endpoint recalculates hashes and flags mismatches.

The log file is append-only by convention

The server never edits individual entries in the audit JSON file — it only writes the full updated array. Do not manually edit compliance-audit.json outside the application. Any manual edit will break a future hash-chain integrity check and will not be detectable without that mechanism enabled.

AI Assistant

Audit Trail includes a right-edge AI Assistant panel that reviews the current page of log entries — timestamp, username, action, module, entity type, entity name, and IP address — and answers natural-language questions about them. Because the audit log is append-only, the assistant is strictly read-only: it never triggers or proposes any mutation, only analysis and summarization.

Activity Summary

Summarizes what happened in the visible window, grouped by user, module, or action type.

Anomaly Spotting

Flags unusual patterns such as a burst of deletes, repeated failed-looking activity, or logins/actions from an unexpected IP address.

User Activity Review

Given a username, summarizes what that user has been doing across modules.

Compliance Narrative

Drafts a plain-language summary of recent activity suitable for a compliance report.

Save Assistant Answers as Reports

Any assistant response can be saved directly to My Reports with one click, so an activity summary or drafted narrative doesn't have to be re-generated later.

Frequently Asked Questions

Are view and download actions logged?

Yes. Both view (opening the document viewer modal) and download (downloading a file) are logged with full entry details. This provides a complete picture of who accessed sensitive documents and when.

Can standard users see the audit trail?

In the current implementation, the Audit Trail screen is accessible to anyone in Compliance Mode. For production deployments, restrict the view to admins by checking the user's role before rendering the screen. RBAC integration is listed in the Functional Requirements spec.

How do I find all actions on a specific document?

The Username search field is not the right filter here. Instead, set the Module dropdown to compliance and narrow the date range, then scan the Entity column for the document name. A dedicated entity-ID filter is planned for a future release.

How long are audit logs kept?

The in-memory store keeps the most recent 5,000 entries. For longer retention (required by ISO 27001, SOC 2, and similar frameworks), schedule a daily export via a cron job and archive the JSON files to cold storage (e.g. S3, Azure Blob). The export endpoint can be called programmatically.

Do audit entries include failed login attempts?

The schema supports a failed_login action type but the current frontend auth flow does not yet emit it. It is listed in the Functional Requirements for a future server-side middleware integration.