K
Klivvr Blog

Building Audit Trails for Financial Systems

A technical guide to implementing comprehensive audit trails in payroll and financial systems using TypeScript, covering event sourcing, immutable logs, and compliance-ready audit infrastructure.

technical8 min readBy Klivvr Engineering
Share:

Audit trails are the backbone of trust in financial systems. Every payroll calculation, every configuration change, every approval decision must be recorded in an immutable, queryable log. Regulators demand it, auditors expect it, and when something goes wrong, the audit trail is the first place everyone looks.

In this article, we explore how to build a production-grade audit trail for payroll systems in TypeScript. We cover event sourcing fundamentals, the design of an immutable audit log, query patterns for compliance investigations, and the infrastructure that ensures audit data is tamper-evident and always available.

Event Sourcing for Payroll Events

Event sourcing is the natural foundation for an audit trail. Rather than storing only the current state of a payroll record, we store every event that led to that state. The current state is derived by replaying events in order.

interface AuditEvent {
  id: string;
  aggregateId: string;
  aggregateType: AggregateType;
  eventType: string;
  payload: Record<string, unknown>;
  metadata: EventMetadata;
  sequenceNumber: number;
  timestamp: Date;
}
 
type AggregateType =
  | "employee"
  | "pay_run"
  | "pay_stub"
  | "compensation"
  | "benefit_election"
  | "tax_configuration"
  | "deduction_configuration";
 
interface EventMetadata {
  actorId: string;
  actorType: "user" | "system" | "integration";
  ipAddress: string | null;
  userAgent: string | null;
  correlationId: string;
  causationId: string | null;
  source: string;
}
 
class AuditEventStore {
  constructor(private readonly repository: EventRepository) {}
 
  async append(event: Omit<AuditEvent, "id" | "sequenceNumber">): Promise<AuditEvent> {
    const lastSequence = await this.repository.getLastSequenceNumber(
      event.aggregateId
    );
 
    const fullEvent: AuditEvent = {
      ...event,
      id: crypto.randomUUID(),
      sequenceNumber: lastSequence + 1,
    };
 
    await this.repository.append(fullEvent);
    return fullEvent;
  }
 
  async getEvents(
    aggregateId: string,
    afterSequence?: number
  ): Promise<AuditEvent[]> {
    return this.repository.findByAggregate(aggregateId, afterSequence);
  }
 
  async getEventsByType(
    eventType: string,
    from: Date,
    to: Date
  ): Promise<AuditEvent[]> {
    return this.repository.findByTypeAndTimeRange(eventType, from, to);
  }
}

The correlationId links events that are part of the same business operation. When a pay run is processed, it produces events for the pay run itself, individual pay stubs, tax withholdings, and bank transfers. The correlation ID ties them all together, making it possible to trace the full lifecycle of a single payroll execution.

A practical tip: generate the correlation ID at the API boundary---the controller or message handler that initiates the operation---and propagate it through every layer. This practice transforms debugging from guesswork into methodical tracing.

Immutable Log Design

An audit trail is only trustworthy if it cannot be tampered with. Immutability must be enforced at the storage level, not just by application convention.

interface ImmutableLogEntry {
  id: string;
  previousHash: string;
  contentHash: string;
  content: AuditEvent;
  createdAt: Date;
}
 
class ImmutableAuditLog {
  constructor(
    private readonly store: AppendOnlyStore,
    private readonly hasher: HashService
  ) {}
 
  async append(event: AuditEvent): Promise<ImmutableLogEntry> {
    const previousEntry = await this.store.getLatest();
    const previousHash = previousEntry?.contentHash ?? "GENESIS";
 
    const contentString = JSON.stringify(event);
    const contentHash = await this.hasher.hash(
      previousHash + contentString
    );
 
    const entry: ImmutableLogEntry = {
      id: crypto.randomUUID(),
      previousHash,
      contentHash,
      content: event,
      createdAt: new Date(),
    };
 
    await this.store.append(entry);
    return entry;
  }
 
  async verifyIntegrity(
    entries: ImmutableLogEntry[]
  ): Promise<IntegrityVerificationResult> {
    const violations: IntegrityViolation[] = [];
 
    for (let i = 1; i < entries.length; i++) {
      const current = entries[i];
      const previous = entries[i - 1];
 
      if (current.previousHash !== previous.contentHash) {
        violations.push({
          entryId: current.id,
          expectedPreviousHash: previous.contentHash,
          actualPreviousHash: current.previousHash,
          position: i,
        });
      }
 
      const expectedHash = await this.hasher.hash(
        current.previousHash + JSON.stringify(current.content)
      );
 
      if (current.contentHash !== expectedHash) {
        violations.push({
          entryId: current.id,
          expectedPreviousHash: expectedHash,
          actualPreviousHash: current.contentHash,
          position: i,
        });
      }
    }
 
    return {
      verified: violations.length === 0,
      entriesChecked: entries.length,
      violations,
      verifiedAt: new Date(),
    };
  }
}
 
interface IntegrityVerificationResult {
  verified: boolean;
  entriesChecked: number;
  violations: IntegrityViolation[];
  verifiedAt: Date;
}
 
interface IntegrityViolation {
  entryId: string;
  expectedPreviousHash: string;
  actualPreviousHash: string;
  position: number;
}

The hash chain creates a structure similar to a blockchain. Each entry's hash depends on the previous entry's hash, making it computationally infeasible to modify a historical entry without invalidating every subsequent entry. Periodic integrity verification detects any tampering.

Audit Trail for Payroll Operations

With the foundational event store and immutable log in place, we can build domain-specific audit trails for payroll operations.

class PayrollAuditService {
  constructor(
    private readonly eventStore: AuditEventStore,
    private readonly immutableLog: ImmutableAuditLog
  ) {}
 
  async recordCompensationChange(
    employeeId: string,
    previousAmount: number,
    newAmount: number,
    reason: string,
    actor: EventMetadata
  ): Promise<void> {
    const event: Omit<AuditEvent, "id" | "sequenceNumber"> = {
      aggregateId: employeeId,
      aggregateType: "compensation",
      eventType: "compensation.changed",
      payload: {
        previousAmount,
        newAmount,
        changePercentage: ((newAmount - previousAmount) / previousAmount) * 100,
        reason,
      },
      metadata: actor,
      timestamp: new Date(),
    };
 
    const storedEvent = await this.eventStore.append(event);
    await this.immutableLog.append(storedEvent);
  }
 
  async recordPayRunApproval(
    payRunId: string,
    totalAmount: number,
    employeeCount: number,
    actor: EventMetadata
  ): Promise<void> {
    const event: Omit<AuditEvent, "id" | "sequenceNumber"> = {
      aggregateId: payRunId,
      aggregateType: "pay_run",
      eventType: "pay_run.approved",
      payload: {
        totalAmount,
        employeeCount,
        approvedAt: new Date().toISOString(),
      },
      metadata: actor,
      timestamp: new Date(),
    };
 
    const storedEvent = await this.eventStore.append(event);
    await this.immutableLog.append(storedEvent);
  }
 
  async recordPayStubGeneration(
    payStubId: string,
    payRunId: string,
    employeeId: string,
    grossPay: number,
    netPay: number,
    actor: EventMetadata
  ): Promise<void> {
    const event: Omit<AuditEvent, "id" | "sequenceNumber"> = {
      aggregateId: payStubId,
      aggregateType: "pay_stub",
      eventType: "pay_stub.generated",
      payload: {
        payRunId,
        employeeId,
        grossPay,
        netPay,
        generatedAt: new Date().toISOString(),
      },
      metadata: actor,
      timestamp: new Date(),
    };
 
    const storedEvent = await this.eventStore.append(event);
    await this.immutableLog.append(storedEvent);
  }
}

Every significant payroll operation generates an audit event. Compensation changes, pay run approvals, stub generation, tax configuration updates, and benefit election changes are all recorded with the full context of who did what, when, and why.

Querying and Reporting on Audit Data

Audit trails are only useful if they can be queried efficiently. Compliance investigations, external audits, and internal reviews all require different views of the same underlying data.

interface AuditQuery {
  aggregateId?: string;
  aggregateType?: AggregateType;
  eventTypes?: string[];
  actorId?: string;
  dateRange?: { from: Date; to: Date };
  correlationId?: string;
  limit?: number;
  offset?: number;
}
 
interface AuditTrailReport {
  query: AuditQuery;
  events: AuditEvent[];
  totalCount: number;
  generatedAt: Date;
}
 
class AuditQueryService {
  constructor(private readonly repository: EventRepository) {}
 
  async query(params: AuditQuery): Promise<AuditTrailReport> {
    const [events, totalCount] = await Promise.all([
      this.repository.search(params),
      this.repository.count(params),
    ]);
 
    return {
      query: params,
      events,
      totalCount,
      generatedAt: new Date(),
    };
  }
 
  async getEmployeeAuditTrail(
    employeeId: string,
    year: number
  ): Promise<AuditTrailReport> {
    return this.query({
      aggregateId: employeeId,
      dateRange: {
        from: new Date(year, 0, 1),
        to: new Date(year, 11, 31),
      },
    });
  }
 
  async getPayRunAuditTrail(payRunId: string): Promise<AuditTrailReport> {
    return this.query({
      correlationId: payRunId,
    });
  }
 
  async getHighValueChanges(
    threshold: number,
    dateRange: { from: Date; to: Date }
  ): Promise<AuditTrailReport> {
    const events = await this.repository.search({
      eventTypes: ["compensation.changed", "pay_run.approved"],
      dateRange,
    });
 
    const filtered = events.filter((event) => {
      if (event.eventType === "compensation.changed") {
        return (event.payload as { newAmount: number }).newAmount > threshold;
      }
      if (event.eventType === "pay_run.approved") {
        return (event.payload as { totalAmount: number }).totalAmount > threshold;
      }
      return false;
    });
 
    return {
      query: { dateRange, eventTypes: ["compensation.changed", "pay_run.approved"] },
      events: filtered,
      totalCount: filtered.length,
      generatedAt: new Date(),
    };
  }
}

A practical tip: index audit events by correlation ID, aggregate ID, event type, and timestamp. These are the most common query dimensions. For compliance-heavy environments, consider a secondary read-optimized store that projects audit events into denormalized views for fast querying.

Retention and Archival

Audit data accumulates rapidly in a busy payroll system. Retention policies must balance regulatory requirements with storage costs.

interface RetentionPolicy {
  eventType: string;
  retentionPeriodYears: number;
  archiveAfterDays: number;
  deleteAfterArchival: boolean;
}
 
class AuditRetentionManager {
  constructor(
    private readonly policies: RetentionPolicy[],
    private readonly archive: ArchiveStorage,
    private readonly eventStore: AuditEventStore
  ) {}
 
  async enforceRetention(): Promise<RetentionReport> {
    const report: RetentionReport = {
      archived: 0,
      deleted: 0,
      errors: [],
      executedAt: new Date(),
    };
 
    for (const policy of this.policies) {
      const archiveCutoff = new Date();
      archiveCutoff.setDate(archiveCutoff.getDate() - policy.archiveAfterDays);
 
      const events = await this.eventStore.getEventsByType(
        policy.eventType,
        new Date(0),
        archiveCutoff
      );
 
      for (const event of events) {
        try {
          await this.archive.store(event);
          report.archived++;
        } catch (error) {
          report.errors.push({
            eventId: event.id,
            message: error instanceof Error ? error.message : "Unknown error",
          });
        }
      }
    }
 
    return report;
  }
}
 
interface RetentionReport {
  archived: number;
  deleted: number;
  errors: Array<{ eventId: string; message: string }>;
  executedAt: Date;
}

Financial regulations typically require payroll records to be retained for seven years. The retention manager archives older events to cold storage while keeping recent events in the hot path for fast querying.

Conclusion

A well-designed audit trail transforms a payroll system from a black box into a transparent, trustworthy platform. Event sourcing captures every state change with full context. Hash-chained immutable logs provide tamper evidence. Domain-specific audit services ensure that every payroll operation is recorded consistently.

TypeScript's type system brings structure to audit event design. Discriminated unions for aggregate types, strongly typed metadata, and interface-driven storage abstractions ensure that audit infrastructure is as rigorously engineered as the payroll calculations it records.

The patterns described here---event sourcing, hash-chain integrity, correlation-based tracing, and policy-driven retention---provide a comprehensive audit framework that satisfies regulatory requirements, supports external audits, and gives engineering teams the observability they need to operate a financial system with confidence.

Related Articles

business

Scaling Payroll Processing for Growing Organizations

A strategic and technical guide to scaling payroll systems as organizations grow, covering batch processing optimization, infrastructure scaling patterns, and the operational strategies that keep payroll reliable at scale.

10 min read
business

Security Best Practices for Payroll Systems

A comprehensive guide to securing payroll systems, covering data encryption, access controls, PII protection, threat modeling, and the security architecture that protects sensitive employee financial data.

10 min read
business

Digital Payroll Transformation: Strategy Guide

A strategic guide to modernizing payroll operations through digital transformation, covering technology selection, change management, compliance continuity, and the business case for building custom payroll infrastructure.

9 min read