Forem: Robert Goniszewski

Decoupling a Live App with Domain Events (Part 2)

Robert Goniszewski — Sat, 21 Mar 2026 10:15:38 +0000

In Part 1 of this series, we introduced RabbitMQ and built our proof-of-concept: the EventBusService, RabbitMQProvider, a DLX retry pattern, and our first emitter (CommentService.createComment()). By the end of Phase 0, we had one event running reliably in production behind a feature flag.

For Phase 1, we applied this pattern to all Tier 1 services. 14 Zod schemas, 25 queue handlers across 3 consumer classes were built, and emit sites were added to CommentService, RecordService, and OccurrenceCrudHelper. We also added 79 new tests. Here is how we executed Phase 1, the design choices we made, and a tricky bug that changed how we guard event bus access.

The Dual-Write Strategy

Our top priority for Phase 1 was safety. Since IHA has active users, we couldn't risk breaking the app. Switching entirely from direct service calls to event emissions wasn't safe yet.

Instead, we used a dual-write strategy. Services now emit events and run their existing inline side effects. If the event broker fails, the inline call still handles the work, and the user notices nothing.

void this.eventBus
  .emit('record.created', { recordId: record.id, userId, title: "record.title, ... })"
  .catch((err) => {
    logger.error({ err, recordId: record.id }, '[RecordService] Failed to emit record.created event');
  });

The inline side effects below it still run. The event goes to consumers who perform the same side effects redundantly. In Phase 2, once consumers are proven reliable under production load, the inline calls are removed.
The .catch() is crucial. Without it, a rejected emit() promise crashes the Node.js process or clutters the logs. Using void tells TypeScript we're intentionally not awaiting the promise—this is a fire-and-forget action. Once consumers prove reliable under production load in Phase 2, we will remove the inline calls.

Designing the Event Schemas

We added ten new schemas to the four we built in Phase 0. We made a few specific design choices to keep the system robust:

Keep payloads minimal: We only send IDs, not full objects. Consumers fetch the extra data they need. This keeps payloads light and ensures consumers use current data, avoiding stale data from the exact moment of emission.
Include optional fields for update diffs: For events like record.updated, we include the previous values of changed fields.

export const RecordUpdatedPayloadSchema = z.object({
  recordId: z.string().uuid(),
  userId: z.string(),
  title: z.string().optional(),
  // ...other current fields
  previousTitle: z.string().optional(),
  previousVisibility: z.string().optional()
});

This lets the consumer easily check if something important changed (like visibility) without fetching the old state from the database, which prevents race conditions.

Treat visibility changes as distinct events: Instead of bundling visibility changes into regular updates, we created a specific visibility_changed event. These are moderated actions with different rules and consumers.
Only validate UUIDs when guaranteed: We didn't use .uuid() validation for userId because we use Lucia session IDs, not UUIDs. We only strictly validated actual database UUIDs to avoid rejecting valid events.

The Emit Pattern

Every emit site uses a fire-and-forget pattern with .catch() logging. Because our ServiceRegistry doesn't support circular constructor injection, we use a lazy getter for the eventBus. It resolves the service on its first access:

private get eventBus(): EventBusService {
  if (!this._eventBus) {
    this._eventBus = getService<EventBusService>(SERVICE_NAMES.EVENT_BUS_SERVICE);
  }
  return this._eventBus;
}

For static helper classes like record-moderation.helper.ts, we can't use this. Instead, we use a dynamic import:

const { getService: _getService, SERVICE_NAMES: _SERVICE_NAMES } = await import('../../ServiceRegistry');
const eventBus = _getService<import('../../EventBusService').EventBusService>(_SERVICE_NAMES.EVENT_BUS_SERVICE);
void eventBus
  .emit('record.visibility_changed', { recordId, userId: moderatorUserId, visible: !hide, moderatorNote: note })
  .catch((err: unknown) => {
    logger.warn({ recordId, err }, '[RecordModerationHelper] Failed to emit record.visibility_changed event');
  });

Three Services, Three Integration Patterns

CommentService: Added three new emit sites for updating, deleting, and toggling visibility.
RecordService: Added the lazy getter and emit sites for creating, updating, and deleting records. The update payload cleverly includes only the previous values for fields that actually changed.
OccurrenceCrudHelper: This helper touches multiple services and isn't registered in the ServiceRegistry. We made the getter null-safe with a try/catch, which led to an interesting bug.

The EventBus Emit Guard Problem

During testing, we hit a tricky bug with the null-safe getter in OccurrenceCrudHelper. We initially used optional chaining (_eventBus?.emit) to guard the call.

In tests, the mocked ServiceRegistry returns a truthy mock object, but it lacks the .emit method. Because the object isn't null, optional chaining proceeds, tries to call .emit, and throws a TypeError: _eventBus.emit is not a function.

The Fix: We replaced optional chaining with an explicit type guard.

const _eventBusForCreate = this.eventBus;
if (_eventBusForCreate && typeof _eventBusForCreate.emit === 'function') {
  void _eventBusForCreate
    .emit('occurrence.created', payload)
    .catch((err: unknown) => {
      logger.error({ err, occurrenceId: occurrence.id }, '[OccurrenceCrudHelper] Failed to emit occurrence.created event');
    });
}

Checking typeof _eventBusForCreate.emit === 'function' safely verifies the method exists before calling it.

Bounded-Context Consumers

Instead of creating a consumer for every single event, we grouped them by entity context: CommentEventConsumers, RecordEventConsumers, and OccurrenceEventConsumers.

Each class registers its queue bindings in the constructor. A single event can fan out to multiple queues simultaneously. If a cache invalidation handler fails, it doesn't break the search indexer handler.

// record.updated -> re-index + notifications + cache
await eventBus.on<RecordUpdatedPayload>(
  EVENT_NAMES.RECORD_UPDATED,
  QUEUES.SEARCH_INDEXER_RECORD,
  async (payload) => { await this.handleUpdatedIndexing(payload); }
);

await eventBus.on<RecordUpdatedPayload>(
  EVENT_NAMES.RECORD_UPDATED,
  QUEUES.CACHE_INVALIDATION_RECORD,
  async (payload) => { await this.handleCacheInvalidation(payload.recordId); }
);

Testing Strategy

We wrote 79 new tests broken into two main groups:

Schema Contract Tests (38 tests): These catch schema drift. We test valid payloads, missing fields, and invalid UUIDs. Note: Zod v4 strictly checks for UUID v4 formats, so your test fixtures must use valid v4 strings (with a '4' in the 13th position).
Consumer Unit Tests (41 tests): We mocked the dependencies and tested the handler methods directly to ensure they call the right downstream services. No RabbitMQ broker is needed here.

What We Learned

Dual-write works: Running both paths simultaneously was safe because our redundant side effects were idempotent.
Explicit emit guards are necessary: Optional chaining isn't enough when dealing with test mocks. Always check if the method is a function.
Contract tests save time: They caught schema drift three times during development, preventing silent runtime failures.
Group consumers by context: Routing logic is much easier to manage in 3 entity-based files rather than 14 event-based files.
Dynamic imports shine in static helpers: They solve circular dependency risks cleanly without cluttering constructors.

What Comes Next

In Phase 2, we will remove the inline side effects. The consumer will become the only path. We will also extract our tools into a Turborepo monorepo, spinning out the notification and search services into their own isolated processes. Our event boundary work makes this extraction safe and reliable.

Repository Updates (Phase 1):

New Files: 10 Zod schemas (records/occurrences), 3 consumer classes, 69 unit/contract tests.
Modified Files: Constants, index exports, CommentService, RecordService, helper classes, and RabbitMQ initialization.

Robert Goniszewski

Feb 25

From Next.js Monolith to Event-Driven Architecture: Why We Started and What We Built

#nextjs #eventdriven #architecture #refactoring

Comments

11 min read

From Next.js Monolith to Event-Driven Architecture: Why We Started and What We Built

Robert Goniszewski — Wed, 25 Feb 2026 12:08:50 +0000

This is my first post in a short series documenting the migration of It Happened Again (IHA) from a Next.js monolith to a distributed, event-driven architecture. This series documents what was built, what broke, and the things I have learned.

What Is IHA?

IHA is a community platform for tracking recurring events - things that keep happening again and again. Users submit and verify occurrences, leave comments, add tags, earn badges, and get notified when patterns they follow are updated. You can think of it as a structured, community-verified record of things that keep repeating themselves.

The backend handles a few distinct workloads:

Write path: comments, occurrences, reactions, verifications - transactional, user-facing, latency-sensitive.
Side effects: search indexing, notifications, badge awarding, visit aggregation - can tolerate latency, must not block writes.
Read path: record pages, occurrence timelines, user profiles - heavily cached, served via RSC and Redis.
Real-time: SSE streams for live notification delivery to connected users.

For the last few months, all of this lived in a single Next.js application. That made sense in the MVP stage, because it was all in one place. As one can imagine, as the codebase grew, each change started touching too many moving parts.

The Monolith

At the beginning, the backend was simple and clean. A few API routes, a handful of services, a PostgreSQL database, Redis for caching and queues, Meilisearch for full-text search. Standard Next.js setup with some discipline around layering: Presentation -> Application -> Service/Domain -> Infrastructure, dependencies pointing inward.

Then features piled up and refactors became routine, and the monolith started showing cracks.

By early 2026, the numbers looked like this:

Over 130 API routes under api/
70+ services registered in ServiceRegistry
4 infrastructure dependencies: PostgreSQL (via Drizzle ORM), Redis (caching + BullMQ queues), Meilisearch, and our newest addition, RabbitMQ
A ServiceRegistry with async initialization, health checks, bidirectional dependency wiring, and HMR-safe global state management

The ServiceRegistry itself became a significant chunk of infrastructure. It handles registration order, async factory functions, timeout protection on initializeAll(), HMR re-registration detection via globalThis.__servicesRegistered, and graceful degradation in production when a service fails to initialize.

None of that came from bad engineering, but from solving real problems inside one process. At some point, that same complexity became a sign that those parts should be separated.

The Three Pain Points Problem

1. Tight Coupling Between Write and Side-Effect Logic

The clearest example is CommentService.createComment(). Before the migration, the method that saved a comment to the database also called SearchService.indexDocumentNow() and NotificationService.sendCommentNotifications() synchronously before returning.

What it meant in practice:

A sneaky Meilisearch timeout causes the comment creation endpoint to return a 500.
A notification delivery failure rolls back a successful write.
Adding a new side effect (say, awarding a badge for a first comment) requires modifying CommentService and adding another service dependency.

The issue was not code quality, but the boundary between services. Saving a comment and indexing a comment have different failure and latency requirements. When they are coupled, the write path inherits failures from side effects.

2. SSE Scaling

Our NotificationService maintains live SSE connections in an in-process data structure. And this works perfectly for a single instance. But when you start to run two instances - for a deploy, for load, for anything - the connections are split across processes. A notification triggered in instance A cannot reach a user connected to instance B. Simple as that.

The usual fix is Redis pub/sub as a connection broker. I could have bolted that into the monolith, but that would add even more state and coupling to an already busy service. A cleaner approach was to move notification delivery into its own process so it owns SSE connections directly and consumes events.

3. Deploy Coupling

As with the previous point, every backend change - a new field in payload, a fix to a background queue handler, a tweak to notification logic - triggers a full Next.js rebuild. Turbopack could help in development, but the production build is still a monolithic artifact. You cannot deploy just the notification logic without redeploying the entire application.

When notification delivery, search indexing, badge jobs, and the API evolve at different speeds, that coupling starts to release friction.

Why RabbitMQ Instead of Something Simpler?

Good question: IHA already had BullMQ + Redis in the stack. And don't get me wrong, BullMQ is excellent, the app uses it for scheduled jobs, retry queues, and batch processing. The actual question was whether to extend BullMQ for all event-driven side effects or introduce RabbitMQ.

The case for BullMQ alone:

Already in the stack, no new infrastructure
BullBoard can be used for queue inspection
First-class TypeScript support
Solid dead letter queue semantics via removeOnFail

The case for RabbitMQ:

Topic exchanges with routing key patterns: a single events exchange can fan-out comment.created to both search-indexer-comment and notifications-comment queues simultaneously, without the publisher knowing about either consumer (BullMQ queues are point-to-point by design).
Consumer isolation: each consumer service declares its own durable queue bound to the exchange. Adding a new consumer (let's say, a moderation service that wants to review new comments) requires no changes to the publisher.
Cross-process fan-out: when the notification service and search service become separate processes, they each connect to RabbitMQ and bind their own queues. The publisher (EventBusService.emit()) doesn't change.
Protocol-level durability: messages survive broker restarts when declared persistent. RabbitMQ AMQP acknowledgement semantics give us finer control over retry behavior than polling a BullMQ queue.

The answer: use BullMQ for scheduled and batch work (badge processing, visit aggregation, data retention), and RabbitMQ for domain events that need fan-out to multiple consumers.

BullMQ is here to stay as both can coexist. They solve different problems.

The RabbitMQ POC: What Was Built

The proof-of-concept had basically three goals:

Prove the routing topology works (topic exchange + multiple queue bindings per event)
Prove that CommentService.createComment() can emit an event replacing calling services directly
Prove the consumer can reconstruct the required side effects from the event payload

The Interface

As usually, I had to start with an interface so the EventBusService is not coupled to RabbitMQ:

The interface defines four methods: connect(), close(), publish(), and subscribe(). This means we can swap RabbitMQ for any other broker - or for a no-op stub when the feature flag is disabled. The publish method returns a Promise<boolean> (that can be described as "false signals backpressure", as I have learned some time ago), and subscribe is generic over the message type T.

The Event Names and Schemas

Events follow a {entity}.{action} routing key convention. All constants live in src/lib/events/constants.ts:

EVENT_NAMES contains COMMENT_CREATED mapped to the string literal comment.created, COMMENT_UPDATED to comment.updated, RECORD_CREATED to record.created, OCCURRENCE_VERIFIED to occurrence.verified, and so on.

QUEUES maps consumer identifiers to their durable queue names: SEARCH_INDEXER_COMMENT maps to search-indexer-comment, NOTIFICATIONS_COMMENT to notifications-comment, and so on for each consumer-purpose pair.

Payloads are validated with Zod schemas at consumer boundaries. CommentCreatedPayloadSchema requires a commentId as UUID, a userId as string, an occurrenceId as string, a content string, and an optional parentId UUID.

The EventBusService

The new EventBusService is a thin orchestration layer over IMessageBrokerProvider. Its two public methods are emit() and on(). It has message buffering built in: emit() calls before initialize() completes are queued in pendingMessages and flushed once connected, rather than failing silently. The isReady flag guards all publish paths.

The Emit Site

In CommentService, the change from direct calls to event emission reduces the method to its core function: persist the comment, then emit an event. The event payload carries just enough data for consumers to fetch what they need - the commentId, userId, occurrenceId, content, and optional parentId (for nested comments).

Before: createComment() awaited both searchService.indexDocumentNow() and notificationService.sendCommentNotifications() before returning. A failure in either blocked or failed the entire operation.

After: createComment() awaits eventBus.emit(EVENT_NAMES.COMMENT_CREATED, payload) and returns. Search indexing and notification delivery happen asynchronously in consumer handlers. The comment creation endpoint succeeds or fails on its own merits.

The Consumer

CommentCreatedConsumer registers two queue bindings for the same event - one for search indexing, and one for notifications. Both subscriptions use eventBus.on() with the event name EVENT_NAMES.COMMENT_CREATED, but different queue names (QUEUES.SEARCH_INDEXER_COMMENT and QUEUES.NOTIFICATIONS_COMMENT).

RabbitMQ delivers a copy of each published message to both queues. The two handlers then execute independently. A failure in handleIndexing does not affect handleNotifications, and vice versa.

handleIndexing fetches the full comment object via commentService.getComment(commentId) - the event payload carries just the ID, not the full object to keep payloads small and avoid serialization of potentially stale data. Then it calls searchService.indexDocumentNow(). If this throws, the error propagates and RabbitMQProvider NACKs the message, triggering the DLX retry pattern.

handleNotifications delegates to CommentNotificationHelper, which holds the complex notification rules (notify occurrence subscribers, notify parent comment authors, skip the author of the triggering comment, and more). This helper existed before the event bus - the consumer just instantiates it with its dependencies rather than duplicating the logic.

POC: The Good

The core design did hold up. The topic exchange fan-out worked as expected (emitting comment.created once delivers a copy to both search-indexer-comment and notifications-comment). Adding a third consumer (e.g. moderation review queue) requires zero changes to the publisher. Which is one of the main reasons to use events.

The IMessageBrokerProvider interface paid off immediately. For unit tests and for the ENABLE_EVENT_BUS=false code path, I registered a no-op stub with connect, close, publish, and subscribe all returning immediately (or returning false for publish). No RabbitMQ process is needed for tests or for environments where the event bus is disabled.

The CommentNotificationHelper was reused as-is. The consumer delegates complex notification rules to the same helper class that the synchronous path used, rather than just duplicating logic. The helper is instantiated with its dependencies passed as constructor arguments, and it is straightforward to test in isolation.

Typing was meant to be solid, so CommentCreatedPayloadSchema provides runtime validation at consumer entry points, and the inferred TypeScript type CommentCreatedPayload gives compile-time safety on the payload fields. EVENT_NAMES and QUEUES as const objects prevent string literal typos at emit and subscribe sites.

POC: The Bad - Three Bugs That Had To Be Fixed

The initial POC had a few defects. These three were the most interesting and the most useful to fix early.

Bug 1: Single Channel Shared Between Publisher and Consumer

The original RabbitMQProvider used one AMQP channel for both publish() and subscribe(). That looked fine in simple tests, but it caused trouble under higher artificial load. AMQP flow control is channel-scoped, so slow consumers could backpressure the same channel used for publishing.

The fix was to split responsibilities: publishChannel for publish(), consumeChannel for subscribe(). Now slow consumption does not stall publishing. I also run setupDLXInfrastructure() on publishChannel, since exchange assertions can run on any channel.

Bug 2: No Dead Letter Exchange

The first POC had no proper retry or dead-lettering logic. If a handler threw (for example when Meilisearch was temporarily unavailable), messages could just bounce in unhelpful ways and failed payloads were hard to inspect.

I implemented a Dead Letter Exchange (DLX) pattern. Now the infrastructure uses three exchanges and three queue variants per every consumer:

events.dlx: the dead letter exchange. Messages go here when NACKed with requeue=false.
events.retry: a retry exchange. Failed messages are published here with a TTL and then expire back to the main events exchange via x-dead-letter-exchange (on the retry queue).
Per-queue DLQ (e.g. search-indexer-comment.dlq): the permanent dead letter queue for messages that have exhausted all retries.

The retry counter lives in the x-retries message header. On each failed delivery, the handler increments the counter and republishes to the retry queue. After MAX_RETRY_COUNT (3) failures, the message is NACKed with requeue=false and lands in the DLQ, where it can be inspected and replayed from the RabbitMQ Management UI.

RETRY_DELAY_MS is set to 5000 (5 seconds). It is simple and predictable for now. Exponential backoff can be added later.

Bug 3: Consumer Registration Timing

The first draft of initializeServices() registered consumers before serviceRegistry.initializeAll(). CommentCreatedConsumer called registerConsumer(), which resolved EventBusService before its async initialization finished. Subscription calls then ran against a bus that was not connected yet.

We fixed this by deferring consumer registration until after initializeAll() completes. The initializeServices() bootstrap sequence now uses this order:

registerProviders(), registerEventBusServices(), registerCoreServices(), and all other registration calls. These only register service factories with the ServiceRegistry - they do not instantiate or connect anything.
serviceRegistry.initializeAll(). This one awaits each factory in registration order, including the async EventBusService factory that establishes the RabbitMQ connection.
setupBidirectionalDependencies(). Wires up circular references between services that cannot be expressed as constructor dependencies.
initializeRabbitMQConsumers(), guarded by the ENABLE_EVENT_BUS flag. By this point, EventBusService is guaranteed to be connected and ready. Consumers then can safely call eventBus.on() and the broker will accept the subscription.

The ENABLE_EVENT_BUS Feature Flag

Shipping a fundamental change to how side effects are triggered requires a way to turn it off instantly if something goes wrong. The ENABLE_EVENT_BUS environment variable controls whether EventBusService is backed by a real RabbitMQ connection or a no-op stub.

When ENABLE_EVENT_BUS is not set or is false:

No RabbitMQ connection is attempted at startup.
EventBusService is registered with a no-op provider that implements the full IMessageBrokerProvider interface but in practice does nothing: connect() resolves immediately, publish() returns false, subscribe() resolves immediately.
emit() calls in application code do not throw and do not block.
CommentService can safely call getService(SERVICE_NAMES.EVENT_BUS_SERVICE) and emit events that won't be delivered.
The legacy synchronous side-effect path remains in place as a fallback.

When ENABLE_EVENT_BUS=true:

RabbitMQProvider connects during initializeAll().
EventBusService.initialize() awaits the connection before returning.
CommentCreatedConsumer registers its queue bindings against the live broker.
createComment() emits events instead of calling services directly.
The synchronous fallback is bypassed.

The no-op path creates a stub that fully satisfies the IMessageBrokerProvider interface contract. The real path creates a RabbitMQProvider, wraps it in EventBusService, and awaits the connection inside an async factory so ServiceRegistry only marks the service ready once the broker is connected.

This means the migration can be shipped behind the flag, enabled in staging, load tested, validated, and enabled in production without a code change. A rollback is a single environment variable update and a process restart.

Architecture Diagrams

Monolith Architecture (Before)

The current state with pain points annotated:

Target Event-Driven Architecture

The target state with all extracted services:

What Comes Next

The POC established that the pattern works and the bugs are fixable. What remains is doing this systematically.

Phase 1: Systematic decoupling within the monolith

The next services to migrate are RecordService, OccurrenceService, BadgeService (as a consumer), and NotificationService (as a consumer). Each follows the same pattern:

Define the event schema in src/lib/events/schemas/.
Add the EVENT_NAMES and QUEUES constants.
Replace direct side-effect calls in the service with eventBus.emit().
Write a consumer class that handles the side effects.
Register the consumer in initializeRabbitMQConsumers().
Write unit tests for the consumer handlers in tests/unit/.

By the end of Phase 1, the monolith, although more modular, is still a monolith, but the coupling between write paths and side-effect paths is severed. Every side effect is now a consumer of a message queue, and the synchronous call graph becomes significantly more shallow.

Phase 2: Turborepo monorepo and extracting a Hono backend

Once the event boundaries are clean, the next step is process extraction. The plan is to move the ~130 API routes to a standalone Hono application (apps/api) with Bun runtime and use Next.js purely as a BFF (Backend for Frontend) that proxies API calls, with additional headers, and handles SSR. The notification service becomes its own process (apps/notification-service) that subscribes to RabbitMQ and manages SSE connections backed by Redis pub/sub. As for the search indexer and worker jobs, they move to apps/search-service and apps/worker-service.

The new Turborepo monorepo structure will share types and schemas through workspace packages (packages/events, packages/db, packages/shared), so the extracted services have compile-time safety without duplicating definitions.

Part 2 of this series covers Phase 1: the systematic decoupling work, the event schema design decisions, and what I have learned about ordering consumer registration across a service graph with bidirectional dependencies. Stay tuned!

It Happened Again - Building a Platform for Tracking Recurring Events

Robert Goniszewski — Wed, 18 Feb 2026 10:43:33 +0000

We repeatedly encounter "unprecedented" events that, on inspection, are anything but unprecedented. The problem is rarely lack of information - it's lack of structure.

Social platforms feel too chaotic, ephemeral, and optimize for reaction, not continuity. Media covers isolated incidents. Discussions fragment across threads. Anyone trying to track recurring events - political shifts, service outages, regulatory cycles - ends up maintaining spreadsheets or personal notes that go nowhere.

It Happened Again (IHA) is my attempt to solve that problem structurally. It's a platform for tracking recurring events through source-backed timelines rather than discussion threads - built from scratch as a solo project.

From Incidents to Patterns

The core problem is what I call pattern blindness. We observe events, but we rarely preserve their recurrence in a structured, referenceable form.

IHA is built around two domain primitives:

Record - the pattern being tracked (e.g., "Bitcoin Crashes").
Occurrence - a dated, source-backed instance of that pattern (e.g., "The 2022 Crash").

This separation drives the entire design. A Record is not a post. An Occurrence is not a comment. Each has its own lifecycle, ownership rules, verification logic, and visibility constraints.

The timeline is not a UI enhancement - it's the primary interface. Chronology is how patterns actually become visible.

Architecture

The system runs on Next.js 15 (App Router), TypeScript (strict mode), PostgreSQL with Drizzle ORM, and Redis + BullMQ for background processing.

The key architectural decision was enforcing a strict service layer. Route handlers stay thin - validate input, delegate to a service, return a response. Business logic lives in services like RecordService and ModerationService, and database access goes through providers so transaction handling never leaks into routing code.

This might seem like overhead for a solo project, but it paid off quickly by solving two problems that tend to creep in otherwise:

Circular dependencies between domain areas.
Permission logic scattered across the UI layer.

With authorization and business rules centralized in services, I could add features like reputation scoring and moderation workflows without destabilizing unrelated parts of the codebase.

Dual-Identifier Strategy

Every entity carries two identifiers - each serving a different purpose.

UUID v7 serves as the primary key: globally unique and time-ordered, well-suited for indexing. For URLs, I use short NanoIDs, giving clean paths like /rec/bitcoin-crash/occ/V1StGXR8 instead of opaque hex strings.

This keeps URLs readable and shareable while avoiding unnecessary exposure of internal identifiers. A small decision with long-term payoff.

Moderation as Infrastructure

Most platforms treat moderation as an admin overlay. I wanted it to be part of the core architecture from the start.

IHA distinguishes between global and local moderators (scoped to specific Records). Authorization is enforced at the service layer - not conditionally hidden in the UI. All moderation actions are logged through an audit mechanism, and visibility changes use timestamped fields rather than hard deletes, keeping actions reversible and traceable.

Enforcing scope at the service level means moderation logic can't be bypassed through inconsistent entry points. Trust is hard to retrofit, so I made it foundational.

Background Processing and Reliability

Several processes run asynchronously - email delivery, badge recalculation, search indexing, visit aggregation - all through BullMQ workers.

Jobs are idempotent with retry policies and exponential backoff. Critical tasks use deterministic job keys to prevent duplicates. Search operations are wrapped with fallbacks so degraded dependencies fail gracefully instead of cascading.

Reputation scoring runs inside transactions to avoid race conditions and gaming exploits. Badge rarity stats are cached and periodically recomputed, balancing performance with accuracy.

Not the most visible features, but they're what separates a prototype from something that actually holds up in production.

Data Sovereignty and GDPR

Infrastructure runs on EU-hosted servers (Hetzner) behind Cloudflare. More importantly, privacy requirements shaped the data model from the beginning rather than being added later.

Soft-deletion has configurable time windows. Audit logs have retention policies. Analytics are consent-based. Account deletion distinguishes between voluntary anonymization and GDPR erasure.

Aligning legal constraints with the technical design early avoids the painful reality of retrofitting compliance into an already fragile system.

Deliberate Tradeoffs

I consciously avoided:

BaaS - I wanted full control over transactions and data flow.
Microservices - the domain is tightly coupled; splitting it would add complexity without real benefit.
Event sourcing - no clear need for replay mechanisms, so it would be unnecessary overhead.

I'd rather have a monolith I can reason about than a distributed system that fights me. The codebase stays straightforward to navigate and extend.

Closing Thoughts

Building IHA meant working across the entire stack - schema design, background workers, moderation workflows, deployment - and keeping it all coherent as a solo developer. It's been a rewarding exercise in domain-first modeling, operational reliability, and making architectural decisions that hold up over time.

The platform is live at ithappenedagain.fyi.

Grimoire: A Retrospective on Building Open Source Tools

Robert Goniszewski — Wed, 18 Feb 2026 10:37:47 +0000

I created Grimoire to solve a personal problem: most existing bookmark managers were either too basic, overloaded with features I didn’t need, or architecturally heavy for something that should be simple (I was picky). I wanted a simple yet intuitive, self-hosted solution that combined the user experience of a modern web app powered by a database that was easy to back up, inspect, and maintain - preferably SQLite.

What started as an excuse to learn SvelteKit turned into a short-lived but surprisingly popular open-source project. While Grimoire development is currently paused, the journey of building it forced me to confront real trade-offs around architecture, marketing, and technical debt.

The Evolution of the Stack

Grimoire's architecture was never set in stone; it evolved alongside my understanding of the problem.

Phase 1: The MVP (Velocity First)

In the beginning (v0.1.0), I prioritized speed to market. I have chosen PocketBase as a backend-as-a-service to handle authentication, the database, user management, and file storage - so I could focus on the frontend and business logic. This allowed me to ship a Dockerized MVP with categories, tags, and basic CRUD operations very quickly. Of course, it also had a dark mode.

It worked. It was simple. It attracted users.

But it also set the stage for future constraints and obstacles.

Phase 2: The Great Refactor (Architecture First)

As the feature set grew, I hit a wall. The tight coupling with PocketBase made custom logic difficult and the codebase felt unmaintainable in the long run.

In v0.4.0, I made the difficult decision to halt feature development and perform a massive refactor.

Decoupling: I moved away from the BaaS dependency to a custom backend.
Performance: I adopted Bun as the runtime and Drizzle ORM for type-safe database interactions.
Cleanup: I deleted nearly as much code as I wrote, streamlining the application logic.

This pivot resulted in a swifter UI, faster metadata processing, and a codebase that was significantly easier for contributors to navigate.

The lesson there was blunt: early convenience becomes long-term rigidity if you outgrow the abstraction.

Building an Ecosystem

I realized early on that a bookmark manager that requires manual copy-paste is already failing. Grimoire needed to meet users where they were starting: in the browser tab.

To solve this, I developed the Grimoire Companion, a browser extension for Chrome and Firefox.

That required:

designing an external API
documenting it with OpenAPI
implementing token-based authentication
handling secure communication between extension and instance

So I had to buckle up and start properly thinking about stability, security, and versioning.

The Challenges of In-Flight Changes

The most complex technical challenge was not building features, but taking responsibility for existing users' data. When I moved from PocketBase to Drizzle, I could not leave them behind.

I had to engineer a dedicated migration tool to map data from the old schema to the new structure, ensuring users preserved their bookmarks, tags, and stored images during the upgrade. Even though Grimoire was far from being stable and could easily lack backward compatibility, I have chosen to do it the proper way, even if that meant a lot more work to do.

Empathy for the user often manifests as robust migration scripts.

Current Status: On the Shelf

After a successful run and multiple releases, I decided that Grimoire achieved what I needed it to.

The landscape of web development moves fast. While the current iteration served its purpose well, I have paused active development to focus on other projects. I may resurrect Grimoire in the future, but with a fresh perspective, aiming for different goals and likely leveraging a more modern approach (perhaps focusing more heavily on AI-driven organization or local-first architectures).

For now, the code remains open and available as a reference implementation for a modern SvelteKit application.

Technical Stack Overview

Frontend: SvelteKit 2 (Vite 5)
Runtime: Bun
Database: Drizzle ORM (SQLite/PostgreSQL)
Auth: Lucia
Infrastructure: Docker Compose

Repo: github.com/goniszewski/grimoire

Forem: Robert Goniszewski

Decoupling a Live App with Domain Events (Part 2)

The Dual-Write Strategy

Designing the Event Schemas

The Emit Pattern

Three Services, Three Integration Patterns

The EventBus Emit Guard Problem

Bounded-Context Consumers

Testing Strategy

What We Learned

What Comes Next

Previous Post

From Next.js Monolith to Event-Driven Architecture: Why We Started and What We Built

From Next.js Monolith to Event-Driven Architecture: Why We Started and What We Built

What Is IHA?

The Monolith

The Three Pain Points Problem

1. Tight Coupling Between Write and Side-Effect Logic

2. SSE Scaling

3. Deploy Coupling

Why RabbitMQ Instead of Something Simpler?

The RabbitMQ POC: What Was Built

The Interface

The Event Names and Schemas

The EventBusService

The Emit Site

The Consumer

POC: The Good

POC: The Bad - Three Bugs That Had To Be Fixed

Bug 1: Single Channel Shared Between Publisher and Consumer

Bug 2: No Dead Letter Exchange

Bug 3: Consumer Registration Timing

The ENABLE_EVENT_BUS Feature Flag

Architecture Diagrams

Monolith Architecture (Before)

Target Event-Driven Architecture

What Comes Next

Phase 1: Systematic decoupling within the monolith

Phase 2: Turborepo monorepo and extracting a Hono backend

It Happened Again - Building a Platform for Tracking Recurring Events

From Incidents to Patterns

Architecture

Dual-Identifier Strategy

Moderation as Infrastructure

Background Processing and Reliability

Data Sovereignty and GDPR

Deliberate Tradeoffs

Closing Thoughts

Grimoire: A Retrospective on Building Open Source Tools

The Evolution of the Stack

Phase 1: The MVP (Velocity First)

Phase 2: The Great Refactor (Architecture First)

Building an Ecosystem

The Challenges of In-Flight Changes

Current Status: On the Shelf

Technical Stack Overview