Audit Logs

Comprehensive audit trail for compliance and debugging. Tracks user actions, data changes, and access patterns across the entire system. Every significant operation is logged with who, what, when, where, and change details.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Routes	backend/src/routes/auditLogs.ts
Middleware	backend/src/middleware/auditLogger.ts
Components	frontend/src/components/audit-log/ (8 files)
Queries	frontend/src/lib/queries/activityQueries.ts

Database Tables

Table	Purpose
auditLogs	System-wide audit trail — every significant action with full context
activityLogs	Lightweight activity feed for UI display (recent actions per entity)

Log Entry Structure

Each audit log entry captures:

Field	Purpose
userId	Who performed the action (user reference)
action	What happened (e.g., create, update, delete, login, export)
entityType	Which entity type was affected (e.g., building, project, document)
entityId	UUID of the affected entity
timestamp	When the action occurred
details	JSON payload with change data (before/after values)
requestId	UUID for correlating multiple log entries from a single HTTP request
ipAddress	Client IP for security auditing

Middleware Integration

The auditLogger middleware (backend/src/middleware/auditLogger.ts) automatically captures:

• Request tracking — assigns a UUID to each request for log correlation
• Mutation logging — records create, update, and delete operations with change diffs
• Auth events — login, logout, failed attempts, 2FA verification
• Access patterns — sensitive data access (exports, bulk operations)

The middleware integrates into the Backend Architecture middleware stack and runs after RBAC Authorization checks.

Frontend Components

Component	Purpose
AuditLogTable	Paginated, filterable table of audit entries
AuditLogDetail	Expanded view of a single log entry with change diff
AuditLogFilters	Filter by user, action, entity type, date range
ActivityFeed	Compact recent-activity timeline shown on entity detail pages
ActivityItem	Single activity entry with icon, description, and timestamp

Query Patterns

• Entity history — fetch all audit entries for a specific entity (entityType + entityId)
• User activity — fetch all actions by a specific user
• Request correlation — trace all side effects of a single request via requestId
• Date-range queries — compliance reporting for specific time periods

Relationships

AuditLog *──1 Users (actor)
AuditLog ──> any entity (via entityType + entityId)
ActivityLog *──1 Users (actor)
ActivityLog ──> any entity (via entityType + entityId)

Related Pages

Users | RBAC Authorization | Admin Dashboard | Backend Architecture | Service Layer Pattern | Database Architecture