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
audit_logs	System-wide audit trail — every significant action with field-level change data
activity_logs	Building-anchored collaboration feed — comments, action items, appointments (scoped task/phase/deal/building)
component_change_logs	Dedicated change tracking for Building Components (field diffs, change reason, automated flag)

Log Entry Structure

Each audit_logs entry captures:

Field	Purpose
userId	Who performed the action (user reference, set null on delete)
action	What happened (e.g., create, update, delete)
entityType / entityId	Which entity was affected (e.g., building, project, document)
oldValue / newValue	JSONB before/after values
componentField / changeType	Field-level change descriptor
buildingId	Building context (cascade)
sessionId	Session that performed the action (set null)
ipAddress / userAgent	Client metadata for security auditing
createdAt	When the action occurred

Attribution note (Human FK rule): audit_logs.userId still references users.id — a grandfathered legacy FK. New attribution columns must reference contacts.id (durable identity); e.g., workflow_transition_log.actorId was migrated to contacts.id in PR#1931 (I#1759). See Contacts.

Activity Logs

activity_logs is not a mirror of the audit trail — it is the user-facing activity/collaboration feed. Entries are anchored on a building (buildingId required) with optional projectId, quoteId, and workflow-package references, carry an authorId, free-text content, and support action-item fields (assigneeId, dueDate, completedAt) and appointment fields (appointmentDate, appointmentType, scheduledDate) — see Appointments.

Middleware Integration

The auditLogger middleware (backend/src/middleware/auditLogger.ts) provides:

• Mutation logging — logEntityChange / withAuditLogging record create, update, and delete operations
• Field-level diffs — createFieldChanges compares old/new objects into per-field change records
• Request metadata — extractRequestMetadata captures IP address and user agent

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
• Building history — fetch all audit entries for a building via buildingId
• Date-range queries — compliance reporting for specific time periods

Relationships

AuditLog *──1 Users (actor, legacy FK)
AuditLog *──1 Building (context)
AuditLog *──1 Session
AuditLog ──> any entity (via entityType + entityId)
ActivityLog *──1 Building (anchor, required)
ActivityLog *──1 Users (author)
ActivityLog ──> Project / Quote / Workflow Package (optional context)

Related Pages

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