DEV Community: Kuba

CQRS + Event Sourcing in NestJS: A Real-World Deep Dive

Kuba — Thu, 09 Apr 2026 11:42:22 +0000

If you've ever worked on a system where "update this record" becomes a landmine — bugs appearing from nowhere, audit logs you can't trust, state that's impossible to replay — you've felt the pain that CQRS and Event Sourcing were designed to solve.

This isn't a "what is CQRS" post. There are a hundred of those. This is a how to actually implement it in NestJS, including the parts nobody talks about: the projections, the event store, the versioning headaches, and what you gain (and lose) by going all-in.

I've been using this stack in NoteCore, a local-first developer knowledge base I'm building, and the patterns here come directly from production code.

Let's go.

The Problem With Traditional CRUD

Before diving into code, let's establish why this matters.

In classic CRUD, your write and read models are the same table:

// The classic way
async updateNote(id: string, dto: UpdateNoteDto) {
  return this.noteRepository.update(id, {
    title: "dto.title,"
    content: dto.content,
    updatedAt: new Date(),
  });
}

This looks fine until:

You need to know what changed (audit trail, undo/redo)
Your reads and writes have completely different shapes (dashboard aggregates vs. raw entities)
You're building a distributed system where multiple services need to react to changes
You want to replay history to rebuild state or add new projections retroactively

CQRS + Event Sourcing solves all of this — but it comes with a real cost in complexity. I'll be honest about both sides.

The Big Picture

Before any code, here's the mental model:

Command (intent)
    ↓
Command Handler (validates, loads aggregate, applies business logic)
    ↓
Domain Event (fact: "this happened")
    ↓
Event Store (append-only log of all events)
    ↓
Projections (rebuild read models from events)
    ↓
Query Handler (reads from projected read models)

Commands represent intent: CreateNote, ArchiveNote, AddTag.

Events are immutable facts: NoteCreated, NoteArchived, TagAdded.

The event store is your source of truth — not the DB table.

Projections are derived views built by replaying events.

The key insight: you never update state directly. You emit events, and state is always derived by replaying those events.

Project Structure

Here's how I structure a CQRS module:

src/
└── notes/
    ├── application/
    │   ├── commands/
    │   │   ├── create-note/
    │   │   │   ├── create-note.command.ts
    │   │   │   └── create-note.handler.ts
    │   │   └── archive-note/
    │   │       ├── archive-note.command.ts
    │   │       └── archive-note.handler.ts
    │   ├── queries/
    │   │   ├── get-note/
    │   │   │   ├── get-note.query.ts
    │   │   │   └── get-note.handler.ts
    │   │   └── list-notes/
    │   │       ├── list-notes.query.ts
    │   │       └── list-notes.handler.ts
    │   └── events/
    │       ├── note-created.event.ts
    │       └── note-archived.event.ts
    ├── domain/
    │   ├── note.aggregate.ts
    │   └── note.events.ts
    ├── infrastructure/
    │   ├── event-store/
    │   │   ├── event-store.service.ts
    │   │   └── stored-event.entity.ts
    │   └── projections/
    │       ├── note-projection.service.ts
    │       └── note-read.entity.ts
    └── notes.module.ts

This looks like a lot of files. It is. That's the cost. But every file has exactly one responsibility — and when something breaks, you know exactly where to look.

Part 1: The Aggregate

The aggregate is the heart of this pattern. It's where your business logic lives, and it's responsible for:

Validating commands
Emitting domain events
Rebuilding its own state from a stream of events

// domain/note.aggregate.ts
import { AggregateRoot } from '@nestjs/cqrs';
import { NoteCreatedEvent } from './events/note-created.event';
import { NoteArchivedEvent } from './events/note-archived.event';
import { TagAddedEvent } from './events/tag-added.event';

export class Note extends AggregateRoot {
  private id: string;
  private title: string;
  private content: string;
  private tags: string[] = [];
  private archived: boolean = false;
  private version: number = 0;

  // Factory method — prefer this over constructor for creation
  static create(id: string, title: string, content: string, authorId: string): Note {
    const note = new Note();
    note.apply(new NoteCreatedEvent(id, title, content, authorId));
    return note;
  }

  // Reconstitute from event stream (Event Sourcing)
  static reconstitute(events: StoredEvent[]): Note {
    const note = new Note();
    for (const event of events) {
      note.applyFromHistory(event);
    }
    return note;
  }

  archive(): void {
    if (this.archived) {
      throw new Error('Note is already archived');
    }
    this.apply(new NoteArchivedEvent(this.id));
  }

  addTag(tag: string): void {
    if (this.tags.includes(tag)) {
      throw new Error(`Tag "${tag}" already exists`);
    }
    this.apply(new TagAddedEvent(this.id, tag));
  }

  // Event handlers — these mutate state
  // NestJS CqrsModule calls these automatically via apply()
  onNoteCreatedEvent(event: NoteCreatedEvent): void {
    this.id = event.noteId;
    this.title = event.title;
    this.content = event.content;
    this.version++;
  }

  onNoteArchivedEvent(event: NoteArchivedEvent): void {
    this.archived = true;
    this.version++;
  }

  onTagAddedEvent(event: TagAddedEvent): void {
    this.tags.push(event.tag);
    this.version++;
  }

  getId(): string { return this.id; }
  getVersion(): number { return this.version; }
}

Notice the separation:

Business validation happens before apply() — in archive() and addTag()
State mutation happens in on* handlers — always in response to events
The aggregate can be rebuilt entirely from its event history via reconstitute()

This means your Note object's state at any point in time is a pure function of the events that happened to it. That's powerful.

Part 2: Domain Events

Events are simple value objects — immutable facts. They should carry enough data to rebuild state without needing to look anything up.

// domain/events/note-created.event.ts
export class NoteCreatedEvent {
  constructor(
    public readonly noteId: string,
    public readonly title: string,
    public readonly content: string,
    public readonly authorId: string,
    public readonly occurredAt: Date = new Date(),
  ) {}
}

// domain/events/note-archived.event.ts
export class NoteArchivedEvent {
  constructor(
    public readonly noteId: string,
    public readonly occurredAt: Date = new Date(),
  ) {}
}

// domain/events/tag-added.event.ts
export class TagAddedEvent {
  constructor(
    public readonly noteId: string,
    public readonly tag: string,
    public readonly occurredAt: Date = new Date(),
  ) {}
}

Golden rule: Once an event is persisted, it's immutable. You never update events. You never delete events. If you made a mistake, you emit a compensating event.

Part 3: The Event Store

This is the part most tutorials skip. Where do the events actually go?

You need an append-only store. Here's a PostgreSQL-backed implementation:

// infrastructure/event-store/stored-event.entity.ts
import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, Index } from 'typeorm';

@Entity('event_store')
@Index(['aggregateId', 'version'], { unique: true })
export class StoredEvent {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  @Index()
  aggregateId: string;

  @Column()
  aggregateType: string;

  @Column()
  eventType: string;

  @Column({ type: 'jsonb' })
  payload: Record<string, unknown>;

  @Column()
  version: number;

  @CreateDateColumn()
  occurredAt: Date;
}

// infrastructure/event-store/event-store.service.ts
import { Injectable, ConflictException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, DataSource } from 'typeorm';
import { StoredEvent } from './stored-event.entity';

@Injectable()
export class EventStoreService {
  constructor(
    @InjectRepository(StoredEvent)
    private readonly eventRepo: Repository<StoredEvent>,
    private readonly dataSource: DataSource,
  ) {}

  async append(
    aggregateId: string,
    aggregateType: string,
    events: DomainEvent[],
    expectedVersion: number,
  ): Promise<void> {
    await this.dataSource.transaction(async (manager) => {
      // Optimistic concurrency check
      const currentVersion = await manager
        .createQueryBuilder(StoredEvent, 'e')
        .where('e.aggregateId = :aggregateId', { aggregateId })
        .select('MAX(e.version)', 'max')
        .getRawOne();

      const latestVersion = currentVersion?.max ?? -1;

      if (latestVersion !== expectedVersion) {
        throw new ConflictException(
          `Concurrency conflict: expected version ${expectedVersion}, got ${latestVersion}`,
        );
      }

      let version = expectedVersion + 1;

      for (const event of events) {
        await manager.save(StoredEvent, {
          aggregateId,
          aggregateType,
          eventType: event.constructor.name,
          payload: JSON.parse(JSON.stringify(event)),
          version: version++,
        });
      }
    });
  }

  async loadEvents(aggregateId: string): Promise<StoredEvent[]> {
    return this.eventRepo.find({
      where: { aggregateId },
      order: { version: 'ASC' },
    });
  }

  async loadEventsSince(aggregateId: string, version: number): Promise<StoredEvent[]> {
    return this.eventRepo
      .createQueryBuilder('e')
      .where('e.aggregateId = :aggregateId', { aggregateId })
      .andWhere('e.version > :version', { version })
      .orderBy('e.version', 'ASC')
      .getMany();
  }
}

The expectedVersion parameter is critical — it gives you optimistic concurrency. If two requests try to update the same aggregate simultaneously, only one will succeed. The other gets a ConflictException and can retry.

Part 4: Commands and Handlers

Commands express user intent. A command handler loads the aggregate, calls a method, persists the events, and publishes them.

// application/commands/create-note/create-note.command.ts
export class CreateNoteCommand {
  constructor(
    public readonly noteId: string,
    public readonly title: string,
    public readonly content: string,
    public readonly authorId: string,
  ) {}
}

// application/commands/create-note/create-note.handler.ts
import { CommandHandler, ICommandHandler, EventPublisher } from '@nestjs/cqrs';
import { CreateNoteCommand } from './create-note.command';
import { EventStoreService } from '../../infrastructure/event-store/event-store.service';
import { Note } from '../../domain/note.aggregate';

@CommandHandler(CreateNoteCommand)
export class CreateNoteHandler implements ICommandHandler<CreateNoteCommand> {
  constructor(
    private readonly eventStore: EventStoreService,
    private readonly publisher: EventPublisher,
  ) {}

  async execute(command: CreateNoteCommand): Promise<void> {
    const { noteId, title, content, authorId } = command;

    // Create the aggregate — events are buffered inside it
    const note = Note.create(noteId, title, content, authorId);

    // Merge the aggregate with EventPublisher so events get dispatched
    const mergedNote = this.publisher.mergeObjectContext(note);

    // Persist events to the store
    const uncommittedEvents = mergedNote.getUncommittedEvents();
    await this.eventStore.append(
      noteId,
      'Note',
      uncommittedEvents,
      -1, // -1 means "this aggregate should not exist yet"
    );

    // Dispatch events to NestJS event bus (for projections / sagas)
    mergedNote.commit();
  }
}

// application/commands/archive-note/archive-note.handler.ts
@CommandHandler(ArchiveNoteCommand)
export class ArchiveNoteHandler implements ICommandHandler<ArchiveNoteCommand> {
  constructor(
    private readonly eventStore: EventStoreService,
    private readonly publisher: EventPublisher,
    private readonly eventDeserializer: EventDeserializerService,
  ) {}

  async execute(command: ArchiveNoteCommand): Promise<void> {
    const { noteId } = command;

    // Load event stream and reconstitute the aggregate
    const storedEvents = await this.eventStore.loadEvents(noteId);

    if (storedEvents.length === 0) {
      throw new NotFoundException(`Note ${noteId} not found`);
    }

    const domainEvents = storedEvents.map((e) =>
      this.eventDeserializer.deserialize(e),
    );

    const note = Note.reconstitute(domainEvents);
    const mergedNote = this.publisher.mergeObjectContext(note);

    // Business logic — will throw if already archived
    mergedNote.archive();

    // Persist new events
    const uncommittedEvents = mergedNote.getUncommittedEvents();
    await this.eventStore.append(
      noteId,
      'Note',
      uncommittedEvents,
      note.getVersion(),
    );

    mergedNote.commit();
  }
}

Part 5: Projections (The Read Side)

Here's where CQRS really shines. Your read models are completely independent of your write model. They're optimized for queries, not for correctness.

// infrastructure/projections/note-read.entity.ts
import { Entity, Column, PrimaryColumn, UpdateDateColumn } from 'typeorm';

@Entity('notes_read')
export class NoteReadEntity {
  @PrimaryColumn()
  id: string;

  @Column()
  title: string;

  @Column({ type: 'text' })
  content: string;

  @Column()
  authorId: string;

  @Column({ type: 'text', array: true, default: '{}' })
  tags: string[];

  @Column({ default: false })
  archived: boolean;

  @Column()
  version: number;

  @UpdateDateColumn()
  lastProjectedAt: Date;
}

// infrastructure/projections/note-projection.service.ts
import { Injectable } from '@nestjs/common';
import { OnEvent } from '@nestjs/event-emitter';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { NoteReadEntity } from './note-read.entity';
import { NoteCreatedEvent } from '../../domain/events/note-created.event';
import { NoteArchivedEvent } from '../../domain/events/note-archived.event';
import { TagAddedEvent } from '../../domain/events/tag-added.event';

@Injectable()
export class NoteProjectionService {
  constructor(
    @InjectRepository(NoteReadEntity)
    private readonly readRepo: Repository<NoteReadEntity>,
  ) {}

  @OnEvent(NoteCreatedEvent.name)
  async onNoteCreated(event: NoteCreatedEvent): Promise<void> {
    await this.readRepo.save({
      id: event.noteId,
      title: event.title,
      content: event.content,
      authorId: event.authorId,
      tags: [],
      archived: false,
      version: 1,
    });
  }

  @OnEvent(NoteArchivedEvent.name)
  async onNoteArchived(event: NoteArchivedEvent): Promise<void> {
    await this.readRepo.update(event.noteId, {
      archived: true,
    });
  }

  @OnEvent(TagAddedEvent.name)
  async onTagAdded(event: TagAddedEvent): Promise<void> {
    const note = await this.readRepo.findOneBy({ id: event.noteId });
    if (!note) return;

    await this.readRepo.update(event.noteId, {
      tags: [...note.tags, event.tag],
    });
  }
}

Your read model can be denormalized however you want. Want a full-text search index? Add it here. Want a separate notes_by_tag table? Add another projection. The event stream is the source of truth — projections are just cached views.

Part 6: Queries

Queries are the simple side of CQRS. They just read from the projection:

// application/queries/get-note/get-note.query.ts
export class GetNoteQuery {
  constructor(
    public readonly noteId: string,
    public readonly requesterId: string,
  ) {}
}

// application/queries/get-note/get-note.handler.ts
import { QueryHandler, IQueryHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { GetNoteQuery } from './get-note.query';
import { NoteReadEntity } from '../../infrastructure/projections/note-read.entity';
import { NoteDto } from '../dtos/note.dto';

@QueryHandler(GetNoteQuery)
export class GetNoteHandler implements IQueryHandler<GetNoteQuery> {
  constructor(
    @InjectRepository(NoteReadEntity)
    private readonly readRepo: Repository<NoteReadEntity>,
  ) {}

  async execute(query: GetNoteQuery): Promise<NoteDto | null> {
    const note = await this.readRepo.findOneBy({ id: query.noteId });
    if (!note) return null;

    return {
      id: note.id,
      title: note.title,
      content: note.content,
      tags: note.tags,
      archived: note.archived,
    };
  }
}

Queries have zero business logic. They just map database rows to DTOs.

Part 7: The Module

Wiring it all together:

// notes.module.ts
import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { TypeOrmModule } from '@nestjs/typeorm';

// Entities
import { StoredEvent } from './infrastructure/event-store/stored-event.entity';
import { NoteReadEntity } from './infrastructure/projections/note-read.entity';

// Command Handlers
import { CreateNoteHandler } from './application/commands/create-note/create-note.handler';
import { ArchiveNoteHandler } from './application/commands/archive-note/archive-note.handler';

// Query Handlers
import { GetNoteHandler } from './application/queries/get-note/get-note.handler';
import { ListNotesHandler } from './application/queries/list-notes/list-notes.handler';

// Services
import { EventStoreService } from './infrastructure/event-store/event-store.service';
import { NoteProjectionService } from './infrastructure/projections/note-projection.service';
import { EventDeserializerService } from './infrastructure/event-store/event-deserializer.service';

const CommandHandlers = [CreateNoteHandler, ArchiveNoteHandler];
const QueryHandlers = [GetNoteHandler, ListNotesHandler];

@Module({
  imports: [
    CqrsModule,
    TypeOrmModule.forFeature([StoredEvent, NoteReadEntity]),
  ],
  providers: [
    ...CommandHandlers,
    ...QueryHandlers,
    EventStoreService,
    NoteProjectionService,
    EventDeserializerService,
  ],
})
export class NotesModule {}

Part 8: Projection Rebuilding

One of the killer features of Event Sourcing: you can rebuild any projection from scratch at any time.

// infrastructure/projections/projection-rebuilder.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, DataSource } from 'typeorm';
import { StoredEvent } from '../event-store/stored-event.entity';
import { NoteReadEntity } from './note-read.entity';
import { EventDeserializerService } from '../event-store/event-deserializer.service';
import { NoteProjectionService } from './note-projection.service';

@Injectable()
export class ProjectionRebuilderService {
  private readonly logger = new Logger(ProjectionRebuilderService.name);

  constructor(
    @InjectRepository(StoredEvent)
    private readonly eventRepo: Repository<StoredEvent>,
    @InjectRepository(NoteReadEntity)
    private readonly readRepo: Repository<NoteReadEntity>,
    private readonly deserializer: EventDeserializerService,
    private readonly projection: NoteProjectionService,
    private readonly dataSource: DataSource,
  ) {}

  async rebuildAll(): Promise<void> {
    this.logger.log('Starting full projection rebuild...');

    // Wipe the read model
    await this.readRepo.clear();

    // Load all events, ordered by aggregate and version
    const allEvents = await this.eventRepo.find({
      where: { aggregateType: 'Note' },
      order: { aggregateId: 'ASC', version: 'ASC' },
    });

    this.logger.log(`Replaying ${allEvents.length} events...`);

    for (const stored of allEvents) {
      const event = this.deserializer.deserialize(stored);
      // Manually invoke projection handlers (bypassing the event bus)
      await this.projection.handleEvent(event);
    }

    this.logger.log('Projection rebuild complete.');
  }
}

This is something you can't do with traditional CRUD. You want to add a new read model for full-text search? Write the projection, run the rebuilder against your event history, and it's done. No data migration. No backfills. Just replay.

Part 9: Event Versioning (The Hard Part)

Here's where most tutorials end and real life begins. Events live forever — but your code doesn't. What happens when NoteCreatedEvent needs a new field?

Strategy 1: Additive changes only

Add optional fields with defaults. Old events are still valid:

export class NoteCreatedEvent {
  constructor(
    public readonly noteId: string,
    public readonly title: string,
    public readonly content: string,
    public readonly authorId: string,
    public readonly workspaceId: string = 'default', // ← new, optional
    public readonly occurredAt: Date = new Date(),
  ) {}
}

Strategy 2: Upcasters for breaking changes

If you need to change the shape significantly, write an upcaster:

// infrastructure/event-store/upcasters/note-created-v1-to-v2.upcaster.ts
export class NoteCreatedV1ToV2Upcaster {
  upcast(oldPayload: NoteCreatedEventV1): NoteCreatedEventV2 {
    return {
      ...oldPayload,
      workspaceId: 'default', // backfill missing field
      _eventVersion: 2,
    };
  }
}

// infrastructure/event-store/event-deserializer.service.ts
@Injectable()
export class EventDeserializerService {
  private upcasters = new Map([
    ['NoteCreatedEvent_v1', new NoteCreatedV1ToV2Upcaster()],
  ]);

  deserialize(stored: StoredEvent): DomainEvent {
    let payload = stored.payload;

    // Apply upcasters if needed
    const upcasterKey = `${stored.eventType}_v${payload._eventVersion ?? 1}`;
    const upcaster = this.upcasters.get(upcasterKey);
    if (upcaster) {
      payload = upcaster.upcast(payload);
    }

    // Map to the correct event class
    switch (stored.eventType) {
      case 'NoteCreatedEvent':
        return new NoteCreatedEvent(
          payload.noteId,
          payload.title,
          payload.content,
          payload.authorId,
          payload.workspaceId,
        );
      case 'NoteArchivedEvent':
        return new NoteArchivedEvent(payload.noteId);
      default:
        throw new Error(`Unknown event type: ${stored.eventType}`);
    }
  }
}

Versioning is a first-class concern you need to think about before you start writing events to production.

Performance: Snapshots

Loading 10,000 events to reconstitute an aggregate is slow. Snapshots solve this:

// infrastructure/snapshots/snapshot.entity.ts
@Entity('aggregate_snapshots')
export class SnapshotEntity {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  aggregateId: string;

  @Column({ type: 'jsonb' })
  state: Record<string, unknown>;

  @Column()
  version: number;

  @CreateDateColumn()
  createdAt: Date;
}

// In ArchiveNoteHandler (modified)
async execute(command: ArchiveNoteCommand): Promise<void> {
  let note: Note;
  let baseVersion: number;

  // Try loading from snapshot first
  const snapshot = await this.snapshotRepo.findOne({
    where: { aggregateId: command.noteId },
    order: { version: 'DESC' },
  });

  if (snapshot) {
    note = Note.fromSnapshot(snapshot.state);
    baseVersion = snapshot.version;

    // Load only events since the snapshot
    const newEvents = await this.eventStore.loadEventsSince(
      command.noteId,
      snapshot.version,
    );
    note.applyHistoricalEvents(newEvents.map(this.deserializer.deserialize));
  } else {
    const allEvents = await this.eventStore.loadEvents(command.noteId);
    note = Note.reconstitute(allEvents.map(this.deserializer.deserialize));
  }

  // ... rest of handler
}

Take a snapshot every N events (100–500 is a reasonable range).

When NOT to Use This

I'd be doing you a disservice if I didn't say this clearly:

Don't reach for CQRS + Event Sourcing as a default.

Use it when you have:

A genuine need for an audit trail (financial systems, compliance, undo/redo)
Different scaling requirements for reads vs. writes
Multiple consumers of your domain events (other services, analytics, notifications)
Enough domain complexity that the overhead is worth it

Don't use it for:

Simple CRUD apps (users table, settings, basic content management)
Small teams without prior ES experience — the learning curve is steep
Systems where eventual consistency is a hard problem (and you haven't thought it through)

The read model in CQRS is eventually consistent by default. After a command succeeds, the projection might lag by milliseconds. For most use cases this is fine. For others (like showing the user their freshly created note immediately after creation), you need to handle it explicitly — either by returning the data directly from the command handler, or by waiting for the projection to catch up.

The Full Flow: Putting It Together

Here's a controller that uses both sides:

// notes.controller.ts
import { Controller, Post, Get, Body, Param } from '@nestjs/common';
import { CommandBus, QueryBus } from '@nestjs/cqrs';
import { v4 as uuid } from 'uuid';
import { CreateNoteCommand } from './application/commands/create-note/create-note.command';
import { ArchiveNoteCommand } from './application/commands/archive-note/archive-note.command';
import { GetNoteQuery } from './application/queries/get-note/get-note.query';

@Controller('notes')
export class NotesController {
  constructor(
    private readonly commandBus: CommandBus,
    private readonly queryBus: QueryBus,
  ) {}

  @Post()
  async create(@Body() dto: CreateNoteDto) {
    const noteId = uuid();
    await this.commandBus.execute(
      new CreateNoteCommand(noteId, dto.title, dto.content, dto.authorId),
    );
    return { id: noteId };
  }

  @Post(':id/archive')
  async archive(@Param('id') id: string) {
    await this.commandBus.execute(new ArchiveNoteCommand(id));
  }

  @Get(':id')
  async getNote(@Param('id') id: string) {
    return this.queryBus.execute(new GetNoteQuery(id, 'user'));
  }
}

The controller knows nothing about aggregates, events, or projections. It dispatches commands and queries — that's it.

What I Learned Building NoteCore With This Stack

A few things I wish I'd known upfront:

1. Design your events around facts, not operations. NoteContentUpdated is better than UpdateNoteCommand. The event should describe what happened, not what was requested.

2. Keep aggregates small and focused. The bigger the aggregate, the more contention you'll have on optimistic locking. A Workspace that contains everything is a concurrency nightmare.

3. Eventual consistency is a UX problem, not just a technical one. Decide early how you'll handle it in your frontend — loading states, optimistic updates, or explicit polling.

4. The event deserializer is where you pay your technical debt. Keep it clean. It grows over time and becomes load-bearing infrastructure.

5. Projections can diverge. Have a rebuild mechanism ready from day one. You will need it.

Conclusion

CQRS and Event Sourcing aren't silver bullets. They're power tools — they make certain problems dramatically easier, and they add real complexity everywhere else.

The things you get for free: full audit history, time travel debugging, the ability to add new read models without touching existing code, horizontal scaling of reads and writes independently.

The things you pay for: more files, eventual consistency, event versioning, serialization concerns, and a steeper learning curve for new team members.

For NoteCore — where I need local-first sync, undo/redo, and the ability to add AI-powered features retroactively against the full history of user actions — it's absolutely the right call.

For a simple REST API that does CRUD on a few tables? Stick with the simple thing.

Building NoteCore in public — follow the journey on Twitter/X or check out HookScope if you work with webhooks.

If this was useful, a ❤️ helps other developers find it. Comments and questions welcome — especially if you've hit different tradeoffs in your own projects.

Clean Architecture in NestJS — A Practical Guide

Kuba — Mon, 06 Apr 2026 13:06:09 +0000

Building NestJS apps is easy. Building NestJS apps that are still easy to change six months later is a different story.

Clean Architecture gives you a way to structure your code so that business logic doesn't bleed into HTTP handlers, database queries don't dictate your domain model, and swapping infrastructure (say, Postgres → SQLite, or REST → gRPC) doesn't require rewriting half the app.

This guide is practical. We'll build a small feature — managing User entities — and walk through each layer with real code.

The core idea

Clean Architecture revolves around one rule: dependencies point inward.

┌──────────────────────────────────┐
│          Infrastructure          │  HTTP, DB, external APIs
│   ┌──────────────────────────┐   │
│   │      Application         │  Use cases / orchestration
│   │   ┌──────────────────┐   │   │
│   │   │     Domain       │  Entities, ports
│   │   └──────────────────┘   │   │
│   └──────────────────────────┘   │
└──────────────────────────────────┘

Domain — pure business logic, no framework dependencies
Application — use cases that orchestrate domain objects
Infrastructure — NestJS controllers, TypeORM repositories, anything "real"

The domain knows nothing about NestJS. The application knows nothing about Express. Infrastructure wires everything together.

Folder structure

src/
  users/
    domain/
      user.entity.ts
      user.repository.ts        ← port (interface)
    application/
      commands/
        create-user.command.ts
        create-user.handler.ts
      queries/
        get-user.query.ts
        get-user.handler.ts
    infrastructure/
      persistence/
        typeorm-user.repository.ts
        user.orm-entity.ts
      http/
        users.controller.ts
        dto/
          create-user.dto.ts
    users.module.ts

If you're using CQRS (and you should consider it for anything beyond CRUD), separate commands and queries from the start. Retrofitting this later is painful.

1. Domain layer

The domain layer holds your entities and the interfaces (ports) that infrastructure must implement.

domain/user.entity.ts

export class User {
  constructor(
    public readonly id: string,
    public readonly email: string,
    public readonly name: string,
    private readonly createdAt: Date,
  ) {}

  static create(email: string, name: string): User {
    return new User(
      crypto.randomUUID(),
      email,
      name,
      new Date(),
    );
  }

  isOlderThan(days: number): boolean {
    const cutoff = new Date();
    cutoff.setDate(cutoff.getDate() - days);
    return this.createdAt < cutoff;
  }
}

No decorators, no @Column(), no @Injectable(). Just a plain class with behavior. This is intentional — your domain entity should be testable with zero framework setup.

domain/user.repository.ts

export interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  save(user: User): Promise<void>;
}

export const USER_REPOSITORY = Symbol('USER_REPOSITORY');

This is your port. The domain defines what it needs; infrastructure provides it.

2. Application layer

Use cases live here. Each handler does one thing: it receives a command or query, calls domain logic, and persists or returns the result.

application/commands/create-user.command.ts

export class CreateUserCommand {
  constructor(
    public readonly email: string,
    public readonly name: string,
  ) {}
}

application/commands/create-user.handler.ts

import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
import { Inject } from '@nestjs/common';
import { CreateUserCommand } from './create-user.command';
import { User } from '../../domain/user.entity';
import { UserRepository, USER_REPOSITORY } from '../../domain/user.repository';

@CommandHandler(CreateUserCommand)
export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
  constructor(
    @Inject(USER_REPOSITORY)
    private readonly userRepository: UserRepository,
  ) {}

  async execute(command: CreateUserCommand): Promise<string> {
    const existing = await this.userRepository.findByEmail(command.email);
    if (existing) {
      throw new Error(`User with email ${command.email} already exists`);
    }

    const user = User.create(command.email, command.name);
    await this.userRepository.save(user);

    return user.id;
  }
}

Notice what's missing: no HTTP-specific concepts, no TypeORM, no NestJS response objects. This handler works identically whether triggered via REST, a CLI command, or a message queue consumer.

3. Infrastructure layer

Here's where NestJS, TypeORM, and the outside world come in.

infrastructure/persistence/user.orm-entity.ts

import { Entity, Column, PrimaryColumn, CreateDateColumn } from 'typeorm';

@Entity('users')
export class UserOrmEntity {
  @PrimaryColumn('uuid')
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  name: string;

  @CreateDateColumn()
  createdAt: Date;
}

infrastructure/persistence/typeorm-user.repository.ts

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UserRepository } from '../../domain/user.repository';
import { User } from '../../domain/user.entity';
import { UserOrmEntity } from './user.orm-entity';

@Injectable()
export class TypeOrmUserRepository implements UserRepository {
  constructor(
    @InjectRepository(UserOrmEntity)
    private readonly ormRepo: Repository<UserOrmEntity>,
  ) {}

  async findById(id: string): Promise<User | null> {
    const record = await this.ormRepo.findOneBy({ id });
    return record ? this.toDomain(record) : null;
  }

  async findByEmail(email: string): Promise<User | null> {
    const record = await this.ormRepo.findOneBy({ email });
    return record ? this.toDomain(record) : null;
  }

  async save(user: User): Promise<void> {
    await this.ormRepo.save(this.toOrm(user));
  }

  private toDomain(record: UserOrmEntity): User {
    return new User(record.id, record.email, record.name, record.createdAt);
  }

  private toOrm(user: User): UserOrmEntity {
    const entity = new UserOrmEntity();
    entity.id = user.id;
    entity.email = user.email;
    entity.name = user.name;
    return entity;
  }
}

The mapper (toDomain / toOrm) is the key. It keeps your ORM schema and your domain model independent — you can change one without touching the other.

infrastructure/http/users.controller.ts

import { Controller, Post, Body, HttpCode } from '@nestjs/common';
import { CommandBus } from '@nestjs/cqrs';
import { CreateUserDto } from './dto/create-user.dto';
import { CreateUserCommand } from '../../application/commands/create-user.command';

@Controller('users')
export class UsersController {
  constructor(private readonly commandBus: CommandBus) {}

  @Post()
  @HttpCode(201)
  async create(@Body() dto: CreateUserDto): Promise<{ id: string }> {
    const id = await this.commandBus.execute(
      new CreateUserCommand(dto.email, dto.name),
    );
    return { id };
  }
}

The controller is intentionally thin. It validates the request (via DTOs + class-validator), dispatches a command, and returns a response. No business logic here.

4. Wiring it all together

users.module.ts

import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { TypeOrmModule } from '@nestjs/typeorm';
import { UserOrmEntity } from './infrastructure/persistence/user.orm-entity';
import { TypeOrmUserRepository } from './infrastructure/persistence/typeorm-user.repository';
import { USER_REPOSITORY } from './domain/user.repository';
import { CreateUserHandler } from './application/commands/create-user.handler';
import { UsersController } from './infrastructure/http/users.controller';

const CommandHandlers = [CreateUserHandler];

@Module({
  imports: [CqrsModule, TypeOrmModule.forFeature([UserOrmEntity])],
  controllers: [UsersController],
  providers: [
    ...CommandHandlers,
    {
      provide: USER_REPOSITORY,
      useClass: TypeOrmUserRepository,
    },
  ],
})
export class UsersModule {}

The provide/useClass pair is where Dependency Inversion happens. The application layer depends on the USER_REPOSITORY token (a symbol), not on TypeORM directly. Swap useClass to an in-memory repository for tests — zero changes to handlers.

Testing the application layer in isolation

describe('CreateUserHandler', () => {
  let handler: CreateUserHandler;
  let repo: InMemoryUserRepository;

  beforeEach(() => {
    repo = new InMemoryUserRepository();
    handler = new CreateUserHandler(repo);
  });

  it('creates a user and returns its id', async () => {
    const id = await handler.execute(
      new CreateUserCommand('kuba@example.com', 'Kuba'),
    );
    expect(id).toBeDefined();
    const user = await repo.findByEmail('kuba@example.com');
    expect(user?.name).toBe('Kuba');
  });

  it('throws when email already taken', async () => {
    await handler.execute(new CreateUserCommand('kuba@example.com', 'Kuba'));
    await expect(
      handler.execute(new CreateUserCommand('kuba@example.com', 'Other')),
    ).rejects.toThrow('already exists');
  });
});

No NestJS test harness, no database, no HTTP — just fast, focused unit tests.

Common tradeoffs to be aware of

"This is a lot of boilerplate for CRUD." Yes. For a simple 3-field entity, the overhead is real. Clean Architecture pays off when your domain has actual rules — validation, state machines, business constraints. If it's just a thin wrapper over a DB table, CQRS + ports-and-adapters might be overkill.

"Do I need separate ORM and domain entities?" Only if they diverge. If your TypeORM entity maps 1:1 to your domain object with no behavior, merge them for now and split later when needed. The important thing is that your application layer never imports typeorm directly.

"What about aggregates and domain events?" Out of scope for this guide, but a natural next step. Once your User.create() starts needing to publish an event (e.g., to send a welcome email), domain events give you a clean way to do it without coupling to side effects.

Summary

Layer	Contains	Can import
Domain	Entities, value objects, repository interfaces	Nothing external
Application	Command/query handlers, use cases	Domain only
Infrastructure	Controllers, ORM repos, external clients	Application + Domain + NestJS

Start with the domain. Define your ports. Let infrastructure implement them. Keep your handlers framework-free. Test the application layer without spinning up a full NestJS app.

The payoff isn't apparent on day one — it becomes obvious when you need to refactor and the blast radius is small.

If you're building something and applying these patterns, I'd love to see what you're working on — drop a link in the comments.

I Built a Local-First AI Knowledge Base for Developers — Here's What Makes It Different

Kuba — Thu, 02 Apr 2026 10:24:52 +0000

Stop losing context between projects. NoteCore is your second brain, built for devs.

Every developer I know has the same problem.

You finish a project. Six months later you're starting something similar and you know you've solved this exact auth problem before. You know you wrote down why you chose CQRS over a simple service layer in that one architecture doc. You know there was a snippet somewhere that handled exactly this edge case.

But you can't find it. It's buried in Notion, or Obsidian, or a random .md file in a repo you barely remember the name of.

So you solve it again from scratch. You spend two hours re-deriving something you already figured out.

That's the problem NoteCore exists to solve.

What is NoteCore?

NoteCore is a local-first AI knowledge base built specifically for developers. It's not another note-taking app. It's a queryable second brain — you throw in code snippets, architecture decisions, documentation fragments, lessons learned, and you get back answers in natural language.

The stack: Electron + React + Vite on the desktop, a local NestJS + SQLite backend running inside the app, Voyage AI for embeddings, and Claude (claude-sonnet-4-6) for the AI layer. Everything runs on your machine. Your notes never leave unless you explicitly opt into cloud sync.

Let's walk through what actually makes it work.

Semantic Search with Voyage AI Embeddings

Full-text search is table stakes. It's also not good enough.

If you wrote a note titled "JWT refresh token rotation strategy" and later search for "how did I handle token expiry", a keyword search returns nothing. The words don't overlap. But the meaning does — and that's exactly what semantic search solves.

NoteCore embeds every note you save using Voyage AI's voyage-code-2 model, which is optimized specifically for code and technical content. When you write a query, it gets embedded using the same model and we run a cosine similarity search over your entire local vector store.

The result: you can ask questions the way you actually think, not the way you happened to word something six months ago.

// Simplified version of what happens on every search
const queryEmbedding = await voyageClient.embed({
  input: userQuery,
  model: 'voyage-code-2',
});

const results = await vectorStore.similaritySearch(
  queryEmbedding.embeddings[0],
  { topK: 10, threshold: 0.75 }
);

Embeddings are generated locally on save and stored in SQLite alongside the note content. No cloud round-trip on every search — it's fast.

Why Voyage AI over OpenAI embeddings?

Two reasons. First, voyage-code-2 is purpose-built for code — it understands that const handleAuth = async () => and "authentication handler function" are talking about the same thing. Generic text embedding models don't handle this nearly as well.

Second, Voyage AI's pricing model made more sense for a local-first product where we're not batching thousands of requests through a SaaS backend — we're embedding notes one at a time as they're saved.

AI Chat Over Your Notes (Claude)

Search gets you relevant notes. Chat gets you answers.

There's a big difference. When you search, you still have to read through results and connect the dots yourself. When you chat, NoteCore does that for you — it retrieves the most semantically relevant chunks from your knowledge base, injects them into context, and lets Claude synthesize an actual answer.

It works like this:

You ask: "What was my approach to handling optimistic updates in that React project?"
NoteCore runs a semantic search across your notes, pulls the top-k most relevant chunks
Those chunks get injected into a Claude prompt as context
Claude answers based on your actual notes, not generic knowledge

The key design decision here was keeping Claude grounded. We explicitly instruct it not to answer from general knowledge if the answer isn't in your notes. If you haven't written anything about a topic, it tells you that — it doesn't hallucinate an answer and make you think you already figured something out when you didn't.

const systemPrompt = `
You are a personal knowledge assistant. Answer the user's question 
using ONLY the notes provided below as context. 

If the answer is not present in the notes, say so clearly. 
Do not use general knowledge to fill in gaps.

Notes context:
${relevantChunks.map(c => c.content).join('\n\n---\n\n')}
`;

This constraint is actually the most important part of the feature. A second brain that makes things up is worse than useless — it gives you false confidence.

Conversation context

NoteCore maintains conversation history within a session, so you can do multi-turn reasoning over your notes:

"What was my auth approach in that project?"
"Why did I choose that over sessions?"
"Would that still work with the new architecture I'm planning?"

Each follow-up is aware of what came before. The full conversation history gets passed to Claude on each turn, so context accumulates naturally.

BYOK — Bring Your Own Key

This one was non-negotiable for me when designing NoteCore.

Most AI tools that embed an LLM work one of two ways: they either route everything through their own backend (meaning your notes hit their servers, they pay for inference and charge you a margin) or they lock you into a specific model with no flexibility.

NoteCore does neither. With BYOK, you connect your own API keys — Anthropic for Claude, Voyage AI for embeddings — and NoteCore calls the APIs directly from the local backend. We never see your requests, your notes, or your responses.

From the user's perspective it's simple: you paste your keys in settings, they're stored encrypted locally using electron-store with OS-level encryption, and that's it. From that point on, you're billed directly by Anthropic/Voyage at their standard rates. No markup, no middleman.

// Keys are stored encrypted, never in plaintext
await secureStore.set('anthropic_api_key', encrypted(apiKey));

// On each AI request, retrieved and used directly
const key = decrypt(await secureStore.get('anthropic_api_key'));
const client = new Anthropic({ apiKey: key });

Why does this matter? A few reasons:

Privacy. Your notes are your thoughts. Architecture decisions, half-formed ideas, things you're figuring out — none of that should sit on someone else's server.

Cost transparency. You see exactly what you're spending. No opaque "AI credits" that obscure actual API costs.

Model flexibility. When Anthropic ships a new model, you can switch immediately. You're not waiting for us to update our backend. You control which model version you're running.

Trust. Honestly, this one's simple. Developers don't trust SaaS products with their sensitive context by default. BYOK removes the trust requirement entirely.

Why NoteCore Is Different

There are other tools in this space. Obsidian, Notion AI, Mem, Reflect. Here's the honest comparison:

Obsidian is brilliant but its AI features are plugin-dependent, fragmented, and the semantic search story is weak without significant setup. It's also a general-purpose tool — not optimized for code and technical content.

Notion AI requires your notes to live in Notion's cloud. Full stop. If that's fine with you, great. It wasn't fine for me.

Mem and Reflect are cloud-first, subscription-based, and neither is particularly developer-focused. They're optimized for the knowledge worker, not the engineer who wants to query their own code snippets.

NoteCore's specific bets:

Local-first by default. Your data lives on your machine. Cloud sync is opt-in.
Developer-focused embeddings. voyage-code-2 understands code semantically in a way generic models don't.
BYOK as a first-class feature, not an afterthought. You own your API relationships.
Grounded AI. The chat feature answers from your notes, not from the internet or general LLM knowledge.
One-time payment. No subscription. Buy it, own it, use it forever.

The Architecture in Brief

For those who want to understand how the pieces fit:

┌─────────────────────────────────────┐
│           Electron Shell            │
│  ┌─────────────┐  ┌──────────────┐  │
│  │  React UI   │  │ Local NestJS │  │
│  │  (Vite)     │◄─►  + SQLite   │  │
│  └─────────────┘  └──────┬───────┘  │
└─────────────────────────┼───────────┘
                           │ BYOK keys
                    ┌──────▼────────┐
                    │  Voyage AI    │  (embeddings)
                    │  Anthropic    │  (chat)
                    └───────────────┘

The local NestJS backend runs as a child process inside Electron. The React frontend communicates with it over a local HTTP port. SQLite holds both note content and vector embeddings. Everything is single-tenant, single-machine by design.

There's also an optional cloud backend (NestJS + Postgres on Railway) for sync and the web dashboard, but that's entirely opt-in. The app works fully offline with zero cloud dependency.

Current Status

NoteCore is approaching beta. The local backend is complete across all core phases — note management, embedding pipeline, semantic search, AI chat, BYOK. Active work right now is on the onboarding flow, feature flag gating via Gatedly, and packaging via GitHub Releases.

If you're a developer who's felt the pain of losing your own context between projects — this is built for you.

Waitlist is open at notecore.app.

Drop your email. Beta is coming soon and early access will be limited.

Building NoteCore in public. Follow along on X for updates.

Customer Called Me raged at Midnight

Kuba — Tue, 24 Mar 2026 21:34:03 +0000

I Built a Webhook Inspector After a Customer Called Me at Midnight

Two weeks ago I was integrating Stripe webhooks for a client project.
Everything was working fine in development. I deployed to production,
went to sleep, and woke up to a message:

"Hey, payments aren't going through."

I spent 3 hours debugging. The webhook was firing. My server was
receiving it. But something in the payload had changed silently —
no announcement, no deprecation warning. Just a broken handler
and an angry customer.

That's when I decided to build HookScope.

The Problem Nobody Talks About

Webhooks sound simple. Provider sends a POST, you handle it. Easy.

Until you're integrating 5 different providers simultaneously.

Stripe has its signature format. GitHub has another. Shopify does
it differently. Clerk uses Svix under the hood. Przelewy24 — the
Polish payment provider — has its own completely custom verification
flow that I had to reverse-engineer from their docs.

Every provider:

Different header names
Different HMAC algorithms
Different payload formats
Different retry logic

And none of them tell you when they change something.

Two Weeks, One Tool

I gave myself two weeks to build something I'd actually want to use.

The core idea was simple: one place to inspect, debug, and monitor
all your webhooks — regardless of provider.

The technical challenge that took the longest wasn't the inspector
itself. It was combining the CLI tunnel with the dashboard in a way
that felt seamless.

You run one command:

hookscope forward 3000

And instantly your local server is receiving webhooks from Stripe,
GitHub, or any other provider — with full inspection in the dashboard,
signature verification handled automatically, and real-time updates
via WebSockets.

Getting that end-to-end flow to feel instant took most of the two weeks.

The Feature I'm Most Proud Of

Schema drift detection.

Every webhook payload gets flattened into a map of dot-notation
paths and types:

{
  "data.object.amount": "number",
  "data.object.currency": "string",
  "type": "string"
}

On every new request, HookScope diffs the current schema against
the stored baseline. If anything changes — a field removed, a type
changed, a new required field added — you get an alert immediately.

Before your handler crashes. Before a customer calls you.

And for paid users, HookScope automatically generates updated
TypeScript, Zod, Go, and Python types via AI. Schema changes,
types update automatically.

What I Launched With

After two weeks I had:

CLI tunnel written in Go (distributed via Homebrew)
Real-time webhook inspector with WebSocket updates
Automatic signature verification for 5 providers
Schema drift detection with alerts
Email, Slack and Discord notifications
Duplicate detection
Silence detection (alerts when webhooks stop coming)
AI-powered DTO generation

Was it perfect? No. But it solved the exact pain point that woke
me up at midnight two weeks earlier.

The Lesson

The best tools come from real pain.

I didn't build HookScope because it seemed like a good SaaS idea.
I built it because I needed it — and every developer integrating
webhooks needs it too, they just don't know it yet.

If you've ever been burned by a silent webhook change or spent
hours debugging a mysterious 400, give it a try.

It's free to start: app.hookscope.dev

The CLI installs in one command:

brew tap nowackikuba/hookscope
brew install hookscope
hookscope login
hookscope forward 3000

Building in public. Feedback welcome in the comments.

How Stripe Silently Broke My Production App (And How I Built a Fix)

Kuba — Mon, 23 Mar 2026 15:46:10 +0000

How Stripe Silently Broke My Production App (And How I Built a Fix)

It was a Tuesday afternoon. A client called — orders weren't going through.

I checked the logs. Stripe webhooks were coming in, the handler was running, but something was off. After an hour of debugging I found it: Stripe had quietly changed the structure of their payment_intent.succeeded payload. A field I was relying on had moved. No announcement. No deprecation warning. Just a silent change that crashed my production handler.

I fixed it in 20 minutes. But I lost 3 hours total — debugging, deploying, explaining to the client.

That's when I started thinking: why doesn't anyone alert me when a webhook payload changes?

The Problem with Webhooks

Webhooks are deceptively simple. Provider sends a POST request, you handle it. Easy.

Until it isn't.

The real problem is that you don't control the schema. Stripe, GitHub, Shopify — they can change their payload structure at any time. Sometimes they announce it. Often they don't. And you only find out when your handler crashes.

Here's what a typical debugging session looks like:

Something breaks in production
You check logs — no clear error
You manually inspect the last few webhook payloads
You realize a field changed, moved, or disappeared
You fix it, deploy, explain to stakeholders

This happens more than you'd think. Stripe changed their payload structure multiple times last year.

The Solution: Schema Drift Detection

The idea is simple: store a flattened schema for every webhook endpoint, and compare it against every new incoming request.

If the schema changes — alert the developer immediately, before it crashes production.

Step 1: Flatten the payload

Instead of storing the raw JSON, we flatten it into a map of dot-notation paths to primitive types:

function flattenSchema(
  obj: Record<string, unknown>,
  prefix = ''
): Record<string, string> {
  return Object.entries(obj).reduce((acc, [key, value]) => {
    const fullKey = prefix ? `${prefix}.${key}` : key;

    if (Array.isArray(value)) {
      acc[fullKey] = 'array';
      if (value.length > 0 && typeof value[0] === 'object' && value[0] !== null) {
        Object.assign(acc, flattenSchema(value[0] as Record<string, unknown>, `${fullKey}[]`));
      }
    } else if (value !== null && typeof value === 'object') {
      Object.assign(acc, flattenSchema(value as Record<string, unknown>, fullKey));
    } else {
      acc[fullKey] = value === null ? 'null' : typeof value;
    }

    return acc;
  }, {} as Record<string, string>);
}

For example, this Stripe payload:

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 2000,
      "currency": "usd"
    }
  }
}

Becomes:

{
  "type": "string",
  "data.object.id": "string",
  "data.object.amount": "number",
  "data.object.currency": "string"
}

This is our baseline schema. Lightweight, easy to store, easy to compare.

Step 2: Diff the schemas

When a new webhook arrives, we flatten its payload and compare it against the stored baseline:

interface SchemaDiff {
  added: string[];
  removed: string[];
  typeChanged: { field: string; from: string; to: string }[];
}

function diffSchemas(
  previous: Record<string, string>,
  current: Record<string, string>
): SchemaDiff {
  const added = Object.keys(current).filter(k => !(k in previous));
  const removed = Object.keys(previous).filter(k => !(k in current));
  const typeChanged = Object.keys(current)
    .filter(k => k in previous && previous[k] !== current[k])
    .map(k => ({ field: k, from: previous[k], to: current[k] }));

  return { added, removed, typeChanged };
}

function isSchemaDiffEmpty(diff: SchemaDiff): boolean {
  return (
    diff.added.length === 0 &&
    diff.removed.length === 0 &&
    diff.typeChanged.length === 0
  );
}

Step 3: Handle multiple event types

Here's a detail that matters: most providers send different event types to the same endpoint.

Stripe sends payment_intent.succeeded, customer.created, invoice.paid — all to the same webhook URL. You can't compare schemas across different event types or you'll get false positives on every request.

The solution: store schemas per endpoint AND per event type.

// schemas stored as: Record<eventType, Record<fieldPath, type>>
{
  "payment_intent.succeeded": {
    "data.object.amount": "number",
    "data.object.currency": "string"
  },
  "customer.created": {
    "data.object.email": "string",
    "data.object.name": "string"
  },
  "__default__": {
    // for webhooks without an event type field
  }
}

Step 4: Wire it up

In NestJS, this lives in a scanner service that runs as a BullMQ background job after every incoming webhook:

@Injectable()
export class SchemaDriftScanner implements ScanServicePort {
  async scan(context: ScanContext): Promise<void> {
    if (!context.payload) return;

    const flattenedPayload = flattenSchema(context.payload);
    const endpoint = await this.endpointRepository.findById(context.endpointId);
    if (!endpoint) return;

    const eventTypeKey = context.eventType ?? DEFAULT_EVENT_TYPE_KEY;
    const targetSchema = endpoint.schemas?.[eventTypeKey];

    if (!targetSchema) {
      // First request — save as baseline, no alert
      endpoint.saveSchema(flattenedPayload);
      await this.endpointRepository.save(endpoint);
      return;
    }

    const diff = diffSchemas(targetSchema, flattenedPayload);

    if (!isSchemaDiffEmpty(diff)) {
      // Schema changed — emit alert event
      this.eventBus.publish(new AlertDetectedEvent({
        type: 'schema_drift',
        endpointId: context.endpointId,
        userId: context.userId,
        eventType: context.eventType,
        metadata: AlertMetadata.schemaDrift(diff),
      }));

      // Update baseline
      endpoint.saveSchema(flattenedPayload);
      await this.endpointRepository.save(endpoint);
    }
  }
}

The full pipeline looks like this:

POST /webhooks/:endpointId
  → verify signature
  → save request to DB
  → emit WebSocket event (live inspector)
  → enqueue ScanWebhookJob

ScanWebhookJob (BullMQ)
  → SchemaDriftScanner.scan()
  → DuplicateScanner.scan()

AlertDetectedEvent
  → save to DB
  → send email/Slack/Discord notification

Taking It Further: Auto-Generated Types

Detecting drift is useful. But what if the tool could also fix it for you?

When a schema drift alert fires, we use the Claude API to automatically generate updated TypeScript, Zod, Go, and Python types from the new schema:

// Input: flattened schema
{
  "data.object.amount": "number",
  "data.object.currency": "string",
  "data.object.total": "number"  // new field
}

// Output: updated NestJS DTO
export class DataObjectDto {
  @IsNumber()
  amount: number;

  @IsString()
  currency: string;

  @IsNumber()
  total: number; // automatically added
}

No manual work. Schema changes, types update automatically.

The Result

After building this into HookScope, I tested it against my own Stripe integration. Within minutes of changing a test payload structure, I got an alert with the exact diff — and an auto-generated updated DTO ready to copy into my codebase.

That 3-hour debugging session? It would have been a 5-minute fix.

Key Takeaways

Flatten your schemas — dot-notation paths make diffing trivial
Store per event type — or you'll get false positives on every request
Run async — never block the webhook response for scanning
Fail safe — if scanning fails, the webhook should still be processed
Default key for unknown event types — __default__ as a fallback

The full implementation is live at app.hookscope.dev if you want to see it in action.

If you've ever been burned by a silent webhook schema change, I'd love to hear about it in the comments.