Edit History Audit Trail — Developer Guide

Overview

The Edit History Audit Trail provides field-level change tracking across five core entity types: Products, Services, Blog Posts, Malets, and Organizations. Every time a Malet Owner or admin updates an entity, the system records precisely which fields changed, their previous and new values, and who made the change. For tracking role-level access changes, see the Custom RBAC audit events and Organization audit feed.

Architecture

graph TD
    A["ProductSyncService.updateOne()"] --> E["EditHistoryService.logEdit()"]
    B["ServiceSyncService.updateOne()"] --> E
    C["BlogQueryService.updateOne()"] --> E
    D["OrganizationResolver.updateOrganization()"] --> E

    E --> F["computeDiff(before, after, trackedFields)"]
    F -->|"changes detected"| G["MongoDB: edit_history collection"]
    F -->|"no changes"| H["Skip (return null)"]

    I["productEditHistory query"] --> J["EditHistoryService.getHistory()"]
    K["maletActivityFeed query"] --> L["EditHistoryService.getHistoryByMalet()"]
    J --> G
    L --> G

    style G fill:#6366f1,color:#fff
    style E fill:#8b5cf6,color:#fff
    style H fill:#64748b,color:#fff

Design Decisions

Schema

EditHistory Entity

The shared entity lives in libs/common and is registered with Typegoose in every subgraph that imports EditHistoryModule:

// libs/common/src/entities/edit-history.entity.ts

@ObjectType()
@Directive('@shareable')
@modelOptions({
	schemaOptions: { timestamps: true, collection: 'edit_history' }
})
@index({ entityType: 1, entityId: 1, createdAt: -1 })
@index({ maletId: 1, createdAt: -1 })
@index({ actorId: 1, createdAt: -1 })
export class EditHistory {
	id: string; // nanoid
	entityType: EditHistoryEntityType; // PRODUCT | SERVICE | MALET | BLOG_POST | ORGANIZATION
	entityId: string; // ID of the entity that was edited
	maletId?: string; // Scoping for cross-entity queries
	actorId: string; // User who made the change
	changes: FieldChange[]; // Array of individual field diffs
	summary?: string; // Auto-generated (e.g. "Updated name, basePrice")
	createdAt: Date;
	updatedAt: Date;
}

FieldChange Embedded Type

@ObjectType()
@Directive('@shareable')
export class FieldChange {
	fieldName: string; // e.g. "name", "basePrice", "tags"
	oldValue?: unknown; // JSON-encoded previous value
	newValue?: unknown; // JSON-encoded current value
}

MongoDB Indexes

Tracked Fields by Entity

Each entity defines a whitelist constant that controls which fields trigger audit entries:

Changes to any field not in this list (e.g. updatedAt, totalInventory, __v) are silently ignored.

GraphQL API

Per-Entity History Queries

Each subgraph exposes its own history query. All follow the same pattern with limit/offset pagination.

Products

query {
	productEditHistory(productId: "prod-abc", limit: 20, offset: 0) {
		id
		entityType
		entityId
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

Services

query {
	serviceEditHistory(serviceId: "svc-xyz", limit: 20) {
		id
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

Blog Posts

query {
	blogPostEditHistory(blogId: "blog-123", limit: 10) {
		id
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

Organizations

query {
	organizationEditHistory(organizationId: "org-456", limit: 50) {
		id
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

Malets

query {
	maletEditHistory(maletId: "malet-789", limit: 20) {
		id
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

Cross-Entity Activity Feed

The maletActivityFeed query aggregates edit history across all entity types belonging to a Malet. This powers the "Recent Changes" dashboard for Malet Owners.

query {
	# All edits across a Malet
	maletActivityFeed(maletId: "malet-789", limit: 50) {
		id
		entityType # PRODUCT, SERVICE, BLOG_POST, etc.
		entityId
		actorId
		summary
		createdAt
		changes {
			fieldName
			oldValue
			newValue
		}
	}
}

# Filter to a specific entity type
query {
	maletActivityFeed(maletId: "malet-789", entityType: PRODUCT, limit: 20) {
		id
		entityType
		entityId
		summary
		createdAt
	}
}

Service Layer

Diff Computation

The EditHistoryService.computeDiff() method compares two object snapshots using JSON serialization for deep equality:

// libs/common/src/entities/edit-history.service.ts

computeDiff(
  before: Record<string, unknown>,
  after: Record<string, unknown>,
  trackedFields: string[],
): FieldChange[] {
  const changes: FieldChange[] = [];

  for (const field of trackedFields) {
    const oldStr = JSON.stringify(before[field] ?? null);
    const newStr = JSON.stringify(after[field] ?? null);

    if (oldStr !== newStr) {
      changes.push({
        fieldName: field,
        oldValue: before[field] ?? null,
        newValue: after[field] ?? null,
      });
    }
  }

  return changes;
}

Integration Pattern

Each subgraph follows the same before-snapshot pattern in its updateOne method:

// Example: apps/products/src/product/product.service.ts

async updateOne(id, update, opts) {
  // 1. Snapshot BEFORE state
  const before = await this.model.findOne({ id }).lean().exec();

  // 2. Perform update
  const product = await super.updateOne(id, update, opts);

  // 3. Log edit history (fire-and-forget)
  if (before) {
    this.editHistoryService
      .logEdit({
        entityType: EditHistoryEntityType.PRODUCT,
        entityId: id,
        maletId: before.maletId,
        actorId: opts?.actorId || 'system',
        before,
        after: product.toObject(),
        trackedFields: PRODUCT_TRACKED_FIELDS,
      })
      .catch((err) =>
        this.logger.warn(`Failed to log edit history: ${err.message}`),
      );
  }

  return product;
}

Key detail: The EditHistoryModule must be imported inside the NestjsQueryGraphQLModule.forFeature() imports array — not at the parent module level. This is because ProductSyncService, ServiceSyncService, and BlogQueryService are instantiated within the NestjsQuery child module context and cannot see providers from the parent.

Module Configuration

NestjsQuery Child Context (Products, Services, Blogs)

// apps/products/src/product/product.module.ts

NestjsQueryGraphQLModule.forFeature({
  imports: [
    NestjsQueryTypegooseModule.forFeature([Product]),
    // ↓ MUST be here, not in parent module imports
    EditHistoryModule,
  ],
  resolvers: [{ ... }],
})

Standard Module (Malets, Organizations)

// apps/malets/src/malet/malet.module.ts

@Module({
  imports: [
    // ... other imports
    EditHistoryModule,  // Standard position — works fine
  ],
  providers: [
    MaletHistoryResolver,
    // ...
  ],
})

GraphQL Federation Composition

The EditHistory and FieldChange types are defined in libs/common and exposed via GraphQL in every subgraph that imports EditHistoryModule. Without the @shareable directive, the federation gateway rejects the supergraph composition because the same type appears in multiple subgraphs.

@ObjectType()
@Directive('@shareable')  // ← Required for Federation 2
export class EditHistory { ... }

@ObjectType()
@Directive('@shareable')  // ← Required for Federation 2
export class FieldChange { ... }

This follows the same pattern used by other shared types in the codebase: Money, Currency, Pricing, etc.

Affected File Map

libs/common/src/entities/
├── edit-history.entity.ts       # EditHistory + FieldChange + EditHistoryEntityType enum
├── edit-history.service.ts      # logEdit(), computeDiff(), getHistory(), getHistoryByMalet()
├── edit-history.module.ts       # Typegoose registration + service export
├── edit-history.service.spec.ts # 15 unit tests
└── index.ts                     # Barrel exports

apps/products/src/product/
├── product.module.ts            # +EditHistoryModule in forFeature imports
├── product.service.ts           # +before-snapshot + logEdit in updateOne
├── product.service.spec.ts      # +EditHistoryService mock
└── product-history.resolver.ts  # NEW: productEditHistory query

apps/services/src/service/
├── service.module.ts            # +EditHistoryModule in forFeature imports
├── service.service.ts           # +before-snapshot + logEdit in updateOne
├── service.service.spec.ts      # +EditHistoryService mock
└── service-history.resolver.ts  # NEW: serviceEditHistory query

apps/blogs/src/blog/
├── blog.module.ts               # +EditHistoryModule in forFeature imports
├── blog.query-service.ts        # +before-snapshot + logEdit in updateOne
├── blog.query-service.spec.ts   # +EditHistoryService mock
└── blog-history.resolver.ts     # NEW: blogPostEditHistory query

apps/malets/src/malet/
├── malet.module.ts              # +EditHistoryModule + MaletHistoryResolver
└── malet-history.resolver.ts    # NEW: maletEditHistory + maletActivityFeed queries

apps/organizations/src/
├── organization/organization.module.ts    # +EditHistoryModule + OrgHistoryResolver
├── organization/organization.resolver.ts  # +before-snapshot + logEdit in updateOrganization
├── organization/organization.resolver.spec.ts  # +EditHistoryService mock
└── audit/org-history.resolver.ts          # NEW: organizationEditHistory query

Testing

Unit Tests

# EditHistoryService (15 tests — diff, log, query)
npm run test -- libs/common/src/entities/edit-history

# All affected subgraphs (381 tests across 49 suites)
npm run test -- libs/common apps/products/src apps/services/src apps/blogs/src apps/malets/src apps/organizations/src

Key Test Coverage

Retention Policy

The system currently uses indefinite retention — no records are automatically purged. If storage becomes a concern, a TTL-based purge can be enabled with a single MongoDB command:

# Add TTL index to auto-delete records older than 90 days
db.edit_history.createIndex(
  { "createdAt": 1 },
  { expireAfterSeconds: 7776000 }  # 90 days
)

This requires **zero code changes** and **zero downtime**. The TTL index runs as a background MongoDB process.

Frontend Implementation

The Admin Dashboard Edit History tab now renders real edit history data via the maletActivityFeed GraphQL query, replacing the previous placeholder data.

Components

User Flow

1. User navigates to Admin Dashboard → Edit History tab
2. Selects a Malet from the dropdown (auto-selects first)
3. maletActivityFeed query fetches edits scoped to that Malet
4. Entity type filter chips (All, Products, Services, Blog Posts, Malet) refine results
5. Each entry is expandable to show FieldDiff components
6. "Load More" button for pagination (offset-based, 30 per page)

Design Decisions

Future Enhancements

Related

• Soft-Delete & Trash System — Companion data lifecycle feature — soft-deleted records are excluded from list queries but retained for audit history
• Custom RBAC — Custom role lifecycle events (created/updated/deleted/assigned/removed) are logged via the Organization Audit Trail
• Organization & Malet Management — Frontend activity feed showing team actions and setting changes
• Organizations & Permissions — Organization-level audit events and permission infrastructure
• SIEM Event Streaming — Stream Organization Audit Trail events to external SIEM platforms — complementary to field-level edit history for compliance
• Professional Services & Client Portals — Document vault access logging provides a parallel compliance trail alongside field-level edit history
• Advanced Audit Logging UI — Frontend Audit Log panel with filtering, CSV/JSON export, and SIEM webhook management