Audit Logs

The Audit Logging system provides a comprehensive trail of all user actions across the entire application. Every create, update, delete, and status change operation is logged with full details for compliance, troubleshooting, and data recovery.

info

Audit logs are ADMIN-only. Access the audit log at Admin Panel → Audit Log (7th tab).

What Gets Logged

Estimation Modules (6 modules)

All CRUD operations for estimation items:

Module	Actions Logged
Concrete	CREATE, UPDATE, DELETE, DUPLICATE
Labor	CREATE, UPDATE, DELETE
Equipment	CREATE, UPDATE, DELETE
Materials	CREATE, UPDATE, DELETE + pricing overrides
Subcontractor	CREATE, UPDATE, DELETE
Misc	CREATE, UPDATE, DELETE

Core Modules (3 modules)

Bid, scope, and variable operations:

Module	Actions Logged
Bid	CREATE, UPDATE, DELETE, STATUS_CHANGE, DUPLICATE, OST_IMPORT, SHARE_CODE_GENERATED, SHARE_CODE_REVOKED, BID_IMPORTED
Scope	CREATE, UPDATE, DELETE, RESTORE
Variables	Bulk updates for factors/fees

Admin Modules (6 modules)

Admin panel and configuration changes:

Module	Actions Logged
Pricing	CREATE, UPDATE, DELETE, BULK_UPDATE, BULK_DELETE
Rebar Rates	CREATE, UPDATE, DELETE, BULK_UPDATE, BULK_DELETE
Pump Pricing	CREATE, UPDATE, DELETE, BULK_UPDATE, BULK_DELETE
Module Permissions	CREATE, UPDATE, RESET
Employees	CREATE, UPDATE, UPDATE_STATUS, DELETE
Users	CREATE, UPDATE, DELETE, INVITATION_SENT, INVITATION_ACCEPTED
Clients	CREATE, UPDATE, DELETE

Accessing Audit Logs

1

Navigate to Admin Panel

Go to Admin Panel from the main navigation.

2

Open Audit Log Tab

Click the Audit Log tab (7th tab).

3

View Log Entries

The audit log displays in a table with:

• Timestamp
• User (who performed the action)
• Action (CREATE, UPDATE, DELETE, etc.)
• Entity Type (ConcreteItem, Bid, etc.)
• Details (summary of changes)
• Actions (View Details, Restore)

Log Entry Structure

Each audit log entry contains:

Field	Description
Timestamp	When the action occurred
User	Email of user who performed action
Action	Type of action (CREATE, UPDATE, DELETE, etc.)
Entity Type	What was affected (Bid, Scope, ConcreteItem, etc.)
Entity ID	UUID of the affected entity
Bid ID	Link to parent bid (if applicable)
Scope ID	Link to parent scope (if applicable)
Details	JSON snapshot of changes
Snapshot Type	FULL (complete snapshot) or DELTA (changes only)
IP Address	Client IP address

Snapshot Types

FULL Snapshots

Complete entity state captured for:

Action	Purpose
DELETE	Enable restoration
STATUS_CHANGE (critical)	Preserve milestone state (SUBMITTED, AWARDED, LOST)

Example FULL snapshot:

{
  "id": "uuid-123",
  "name": "Foundation Scope",
  "totalCost": 45000.00,
  "multiplier": 1.0,
  "concreteItems": [...],
  "laborItems": [...],
  // ... complete entity
}

DELTA Snapshots

Only changed fields for routine operations:

Action	Purpose
CREATE	Basic info (name, dimensions, cost)
UPDATE	Changed fields only

Example DELTA snapshot:

{
  "changes": [
    {
      "field": "name",
      "oldValue": "Slab",
      "newValue": "Foundation Slab"
    },
    {
      "field": "totalCost",
      "oldValue": 12000.00,
      "newValue": 15000.00
    }
  ]
}

Filtering Audit Logs

By User

Filter to see actions performed by a specific user:

1. Click "Show Filters"
2. Select user from User dropdown
3. Click Apply

By Bid

View all activity for a specific bid:

1. Click "Show Filters"
2. Select bid from Bid dropdown
3. Click Apply

tip

This shows the complete history of a bid: creation, scope additions, item changes, status changes, etc.

By Action

Filter by action type:

1. Click "Show Filters"
2. Select action: CREATE, UPDATE, DELETE, STATUS_CHANGE
3. Click Apply

Use cases:

• DELETE - See all deletions for potential restoration
• STATUS_CHANGE - Track bid lifecycle
• UPDATE - Review recent edits

By Entity Type

View activity for specific entity types:

1. Click "Show Filters"
2. Select entity type: Bid, Scope, ConcreteItem, etc.
3. Click Apply

Example: See all concrete item changes

By Date Range

Filter by date:

1. Click "Show Filters"
2. Set Start Date and End Date
3. Click Apply

Use case: Review activity during specific time periods

Viewing Log Details

1

Expand Row

Click the arrow icon to expand a log entry for quick preview:

Shows:

• Entity ID
• Bid ID
• Scope ID
• Snapshot Type

2

View Full Details

Click "Details" button to see complete JSON snapshot in a modal dialog.

Full JSON includes:

• All changed fields (for DELTA)
• Complete entity state (for FULL)
• Related items (for nested deletions)

Restoring Deleted Entities

Deleted scopes can be fully restored with all their items:

1

Find Deletion Log

Filter by:

• Action: DELETE
• Entity Type: Scope

Find the scope you want to restore.

2

Click Restore Button

Click the orange "Undo" button next to the deletion log entry.

note

Restore button only appears for DELETE actions with FULL snapshots.

3

Confirm Restoration

Review the restoration details:

• Scope name
• Number of items to restore (concrete, labor, equipment, materials, subcontractor, misc)

Click "Restore" to proceed.

4

Verify Restoration

The scope and all its items are restored:

• Original scope with original ID
• All estimation items (6 types)
• Costs recalculated
• Restoration logged in audit trail

warning

Restoration creates a new log entry documenting the restore action.

Bulk Operations Logging

Bulk operations (bulk update/delete) are logged with special metadata:

Bulk Update Log

{
  "bulkUpdate": true,
  "itemCount": 15,
  "updates": ["basePrice", "taxRate"],
  "entityId": "id1,id2,id3,..." // Comma-separated list
}

Bulk Delete Log

{
  "bulkDelete": true,
  "itemCount": 8,
  "deletedItems": [
    { "id": "uuid1", "description": "Dozer 750", "category": "Rental" },
    { "id": "uuid2", "description": "Excavator", "category": "Rental" }
  ],
  "entityId": "uuid1,uuid2,uuid3,..." // Comma-separated list
}

Action Color Coding

The audit log UI uses color-coded badges for quick visual identification:

Action	Color	Meaning
CREATE	Green	New item created
UPDATE	Blue	Item modified
DELETE	Red	Item deleted
STATUS_CHANGE	Orange	Bid status changed
RESTORE	Purple	Deleted item restored

Pagination

Audit logs support pagination for performance:

Setting	Options
Rows per page	50, 100, 200
Navigation	Previous, Next, Jump to page

tip

Use filters to narrow down results before paginating through large audit trails.

Audit Statistics

Click "Stats" to view aggregate statistics:

Metric	Description
Total Log Entries	Total number of audit logs
By Action	Breakdown by CREATE, UPDATE, DELETE, etc.
By Entity Type	Activity per entity type
By User	Most active users
Date Range	Activity over time

API Endpoints

Method	Endpoint	Description	Auth
GET	/api/audit/logs	List logs with filters	ADMIN
GET	/api/audit/logs/:id	Get single log entry	ADMIN
GET	/api/audit/stats	Action/entity/user statistics	ADMIN
POST	/api/audit/restore/:logId	Restore deleted entity	ADMIN

Query Parameters

The /api/audit/logs endpoint supports filtering:

Parameter	Description	Example
userId	Filter by user	?userId=uuid-123
bidId	Filter by bid	?bidId=uuid-456
scopeId	Filter by scope	?scopeId=uuid-789
action	Filter by action	?action=DELETE
entityType	Filter by entity type	?entityType=ConcreteItem
startDate	Start date	?startDate=2025-01-01
endDate	End date	?endDate=2025-01-31
limit	Results per page	?limit=100
offset	Page offset	?offset=50

Storage and Performance

Storage Efficiency

• DELTA logs: ~100 bytes per entry (routine operations)
• FULL snapshots: ~5-10 KB per entry (deletions, milestones)
• Projected: ~75 MB/year for 10 active users

Database Indexes

All key fields are indexed for fast queries:

• userId (DESC)
• bidId (DESC)
• scopeId (DESC)
• entityType (DESC)
• action (DESC)
• timestamp (DESC)

Recent-first queries are optimized.

Data Retention

Audit logs are retained indefinitely for compliance. Future versions may implement archival policies.

Use Cases

Compliance & Auditing

Scenario: Annual audit requires proof of who made changes to bids.

Steps:

1. Filter by date range (audit period)
2. Filter by entity type: Bid
3. Export audit log to CSV
4. Provide to auditors

Troubleshooting

Scenario: Bid total is incorrect, need to trace changes.

Steps:

1. Filter by bid ID
2. Sort by timestamp (chronological order)
3. Review UPDATE and STATUS_CHANGE entries
4. Identify when/who changed pricing

Data Recovery

Scenario: User accidentally deleted a scope, needs restoration.

Steps:

1. Filter by action: DELETE
2. Filter by entity type: Scope
3. Find the deleted scope
4. Click "Undo" to restore

User Activity Review

Scenario: Review a specific user's recent activity.

Steps:

1. Filter by user
2. Set date range (last 7 days)
3. Review all actions performed

Best Practices

📅

Regular Review

Periodically review audit logs to ensure system integrity and identify unusual activity.

🔍

Filter Before Exporting

Apply filters before exporting to CSV to reduce file size and focus on relevant data.

📖

Document Restorations

When restoring deleted entities, document the reason in bid notes or project documentation.

📈

Use Stats for Insights

Review audit statistics to understand usage patterns and identify training opportunities.

Troubleshooting

Cannot find specific log entry

Check:

1. Date range filter (may be excluding the entry)
2. Entity type filter (ensure correct type selected)
3. User filter (log may be by different user)
4. Pagination (entry may be on another page)

Restore button not appearing

Restore button only appears for:

• DELETE actions
• FULL snapshot type
• Scope entities (currently)

Other entity types may not support restoration yet.

Empty details JSON

Some actions (like STATUS_CHANGE between non-critical statuses) may have minimal DELTA snapshots. This is expected behavior.

Excluded from Audit Logs

Certain system-generated actions are excluded to reduce noise:

Entity	Exclusion
Labor Items	"Auto Use" items (auto-managed by system)
System Actions	Background recalculations, auto-saves

Next Steps

👥

User Management

Track user invitation and access changes

🔑

Role Permissions

Review permission configuration changes