Module Federation's pitch is that independently-built, independently-deployed frontends can share code at runtime without a monorepo forcing every team onto the same release train. That pitch is true, and it's also exactly where the risk lives: "shared at runtime" means the thing that used to be a compile error in a monorepo is now a runtime error in production, discovered by whichever customer happens to navigate into the account-opening micro-frontend first after a shell deploy. This is about the two places that actually breaks, and what closes each one. 

What's actually being shared, and why that's the risk surface 

Module Federation lets a host application (the shell) load remote applications (micro-frontends, owned by other teams) at runtime, and — critically for a framework as stateful as Angular — share singleton dependencies like @angular/core and @angular/common between them, rather than each remote shipping its own copy. Sharing is what makes the architecture viable: without it, every micro-frontend bundles its own Angular runtime, bloating every page load and risking two live instances of a framework that assumes there's only one. 

That sharing is also where version drift becomes a production incident instead of a build warning. A monorepo catches an incompatible dependency bump at compile time, for everyone, before it ships. A federated architecture, by design, lets the payments team ship their remote on Tuesday and the accounts team ship theirs on Thursday, and the first place an incompatibility between them shows up is a customer's browser, not a CI pipeline. 

Dependency version drift: what Webpack Module Federation actually does about it 

Webpack's ModuleFederationPlugin resolves shared singleton versions using SemVer at runtime: if the versions requested by the shell and each remote are compatible, it picks the highest one everyone can use. If they aren't compatible, the default behavior is to still pick a version and hope for the best — which for a stateful singleton like Angular's core, is exactly the scenario that produces a Error: Unsatisfied version exception in production, not a build failure anyone caught beforehand. 

    strictVersion: true,       // throw instead of silently picking a version 

    requiredVersion: 'auto',   // pull the actual version from this project's package.json 

strictVersion: true is the setting worth treating as non-negotiable for a banking portal specifically: it converts a silent, best-effort version resolution into a thrown exception the moment an incompatibility is detected, which is a worse-looking error but a genuinely safer one — a loud failure on load beats a subtly broken shared Angular instance serving real account data. requiredVersion: 'auto' matters for a different reason: hand-typed version strings drift out of sync with package.json the first time someone bumps a dependency and forgets the federation config, which is exactly the kind of gap that turns a routine dependency update into an incompatible-version incident three deploys later. 

The failure that isn't a version mismatch at all 

Dependency versioning is the failure mode most Module Federation guidance covers. It's not the one that actually causes the worst incidents on a multi-team portal. The other one is a runtime contract break: a remote module's exposed component changes its public API — a required input becomes optional, an output event gets renamed, a component that used to render synchronously now returns a promise — and the shell, built and deployed independently, has no compiler in the loop to catch the mismatch. Nothing about Module Federation checks that what a remote exposes today still matches what the shell expects, because they're compiled separately, by separate teams, on separate schedules. 

This is the same category of problem as any other integration boundary between independently-deployed services, and it deserves the same discipline: treat every exposed federated module as a versioned public contract, not an internal implementation detail that happens to be reachable from outside the repo. Concretely, that means: 

Explicit input/output contracts on every exposed component, documented and reviewed with the same rigor as a public API — because that's what it actually is, even though it's TypeScript rather than REST. 

Contract tests run against the real built remote, not a mock, in CI, on both sides of the boundary — the shell's pipeline pulls the actual remote's remoteEntry.js (or Native Federation's manifest) and verifies the exposed modules it depends on still match the expected shape, the same instinct behind contract testing tools like Pact at any other service boundary, applied here to a frontend one. 

A deprecation window for any breaking change to an exposed module — old and new versions exposed side by side for a release or two, exactly the same discipline an API team would apply to a breaking endpoint change, because a federated component has the same blast radius as an API a team doesn't control the deploy schedule of. 

Native Federation: faster, but not yet the same flexibility 

Angular's ecosystem has been moving toward Native Federation — an esbuild-based alternative to Webpack's plugin, and the direction the Angular CLI itself is heading, with real build-time improvements teams report (one enterprise migration cited going from roughly 45 seconds to under 10 for a federated build). 

  remotes: { accounts: 'http://localhost:4202/' }, 

    ...shareAll({ singleton: true, strictVersion: true }), 

The syntax is deliberately close to Webpack MF's, which eases migration — but worth knowing before committing a banking portal to it: as of this writing, Native Federation's singleton handling is less flexible than Webpack's. Where Webpack MF can resolve compatible-but-different versions to the highest common one, Native Federation currently expects singleton dependencies to match exactly across the shell and every remote, with community tooling (an in-progress orchestrator project) still catching up to close that gap. For a portal where different teams update dependencies on different schedules, that's a real operational constraint, not a rounding error — worth validating directly against your team's actual dependency-update cadence before migrating, rather than assuming feature parity with Webpack MF. 

The migration doesn't have to be all-or-nothing 

Because Native Federation's manifest format and exposed-module mechanics are close enough to Webpack MF's, teams don't need a single cutover. A shell can stay on Webpack MF while individual remotes migrate to Native Federation independently, module by module, validated against the same contract tests described above before and after the switch — the contract-testing discipline is what actually makes an incremental migration safe, because it's what catches a mismatch introduced by the migration itself, not just by an unrelated dependency bump. 

Neither implementation solves version drift or contract breaks by default — both give you the tools and neither enforces using them. The discipline that holds up in practice is boring on purpose: strictVersion: true everywhere so a bad resolution fails loudly instead of silently, requiredVersion: 'auto' so the federation config can't drift from package.json, and contract tests against real built remotes in CI so a breaking change to an exposed module is caught before a shell deploy ships it to a customer, not after. None of that is exotic. It's the same discipline a well-run API team already applies to any boundary they don't fully control — a federated micro-frontend just makes that boundary look, misleadingly, like it's still inside your own build. 

Module Federation for Banking Portals 

Shared dependency versioning, runtime contract breaks between federated modules, and how to keep a multi-team banking portal from becoming an integration nightmare.

Module Federation lets independent teams ship independent frontends — and turns a compile-time error into a runtime one. Here's what closes that gap.

Micro-Frontends Without the Version Drift 

Most offline-sync guidance defaults to last-write-wins because most offline-sync guidance is written for todo apps and note editors, where overwriting an old value with a newer one is exactly the right behavior. A balance isn't that kind of data, and the moment a banking app's sync layer treats it like it is, the bug isn't cosmetic — it's a customer's money disagreeing with itself across two devices. This is about the model that actually holds up, not a smarter merge algorithm. 

The mistake is upstream of the merge strategy 

Last-write-wins picks the most recent timestamp and discards the other write. That's a reasonable default when two writes are genuinely alternatives to the same field — a display name changed on two devices while offline, where only one final value can possibly be correct and either is an acceptable choice. It's the wrong model entirely for a balance, and the reason isn't that LWW picks badly — it's that a balance was never a field two devices independently "wrote to" in the first place. 

A transaction offline isn't a new value for the balance field. It's an operation — "debit $40" — that gets queued locally and needs to be applied, in some order, alongside whatever else happened to the account while the device was offline. Two devices going offline and each initiating a transaction aren't in conflict with each other the way two edits to a display name are. They're two independent operations that both need to be evaluated against the account's real state, in some deterministic order, by whichever party actually knows what that real state is — which is never the device. 

Treating the queued transaction as "the new balance" is what makes LWW look like a design choice instead of a bug. The fix isn't a better conflict-resolution algorithm layered on top of that model. It's not using that model at all. 

The local outbox should hold operations, not balances — the same distinction we've written about for event-sourced ledgers, applied here on the client instead of the server: the balance is never stored as a value to be synced, it's always derived, and what actually gets queued is the sequence of things that happened. 

  idempotencyKey: string;      // client-generated UUID, stable across retries 

  clientTimestamp: number;     // for display and ordering hints only — 

                                // never the source of truth for ordering 

  status: 'pending' | 'confirmed' | 'rejected'; 

function enqueueTransaction(tx: Omit<QueuedTransaction, 'idempotencyKey' | 'status'>) { 

  applyOptimistically(queued); // UI reflects it immediately, marked pending 

The idempotencyKey is doing exactly the job it does in a payment API — a connectivity drop mid-sync and a retry send the same operation twice, and the server has to treat the second arrival as a replay, not a new debit. That's the same pattern we've covered for preventing duplicate charges at an API boundary; here it protects against a mobile network's flakiness duplicating a sync call instead of a gateway's timeout duplicating a retry, but it's the identical mechanism solving the identical class of problem. 

The optimistic UI has to know it's provisional 

This is the part worth being deliberate about in the interface, not just the data layer: a queued transaction should render as pending, visually distinct from a confirmed one, and the displayed balance should be labeled as provisional until sync confirms it. That single UX decision is what makes the eventual failure case survivable. If the optimistic balance is presented with the same visual authority as a confirmed one, a rejected transaction has nowhere honest to land — the user was shown a number that turned out to be wrong, with no indication it was ever anything less than final. If it was always shown as pending, a rejection is just the pending state resolving to "didn't go through," which is a UX pattern users already understand from every other app that queues actions offline. 

The server is the only party allowed to decide what happened 

When connectivity returns, the queued operations sync — and this is where the actual conflict resolution happens, not on the device. The server applies each operation against the account's real, current state, in the order it receives them (or in a deterministic order it assigns, such as a per-account sequence number issued at acceptance time — never a client-supplied timestamp, because clock skew between two devices is a real and unresolvable problem if the server trusts it for ordering). 

Two offline transactions that are each individually valid can still be jointly invalid — a withdrawal from each of two devices that, combined, overdraw an account neither device knew was close to its limit. That's not a sync conflict in the CRDT sense; there's nothing to merge. It's a business rule, evaluated once, by the party with authoritative state, and the second operation the server processes gets rejected outright rather than silently adjusted, merged, or clamped to whatever the account can actually cover. 

// Server-side, conceptually — the client never re-derives this itself 

function applyQueuedTransaction(tx: QueuedTransaction, account: Account) { 

  if (isDuplicate(tx.idempotencyKey)) return getStoredResult(tx.idempotencyKey); 

  if (tx.type === 'debit' && account.balance < tx.amount) { 

    return reject(tx, 'INSUFFICIENT_FUNDS'); 

  const result = ledgerService.apply(tx); // becomes an event in the ledger, per earlier piece 

  storeResult(tx.idempotencyKey, result); 

The client's job on sync response is simple precisely because the hard decision didn't happen there: mark each QueuedTransaction as confirmed or rejected based on what the server actually decided, update the locally-derived balance display to match the server's authoritative value, and surface a rejection to the user explicitly — never resolve it silently by quietly adjusting a number the user already saw. 

The cost is real and worth naming to whoever's reviewing the architecture: transactions initiated offline aren't final until sync completes, and the UI has to carry that honestly rather than pretending otherwise, which is more interface work than a naive "just update the local balance" implementation. What it buys is the thing last-write-wins can never provide for money: a balance that's always traceable to a sequence of operations a server actually evaluated, with no version of events where two devices' local state disagreed about how much money existed and something silently picked a winner. The device queues intent. It was never supposed to decide outcome — and building the sync layer as if it does is where "just use last-write-wins" quietly turns into a support ticket about a balance nobody can explain. 

Offline-First React Native Banking Apps 

Conflict-resolution strategies for locally-queued transactions, and why last-write-wins is the wrong default when money is involved.

Last-write-wins works for a display name. It's the wrong model for a balance, because two offline transactions were never conflicting writes to begin with.

Sync Conflict Resolution That Doesn't Corrupt Balances

Every "add a column" migration looks identical in a code review — one line, obviously safe. What that line actually does to a live table under load depends entirely on which lock Postgres decides to take, and that's the part a code review can't see. On a core banking transaction table taking writes continuously, the wrong lock isn't a slow deploy. It's every payment in flight queuing behind a migration until it either finishes or the connection pool empties. This is what actually determines which side of that line a migration falls on, and the sequence that keeps you on the safe one. 

Expand-contract is the governing pattern, not one technique among several 

The single rule worth internalizing before any specific syntax: never make a breaking schema change in one step, on one table, in one deploy. Expand first — add the new structure alongside the old, in a form existing code doesn't need to know about yet. Migrate the application to write to both, or to the new structure only, deployed independently of the schema change. Backfill historical data in the background. Only then contract — remove what's no longer needed, once nothing still depends on it. Every pattern below is a specific instance of that sequence; the sequence is what actually delivers zero downtime, not any individual command. 

Adding a column: the default matters more than the column 

ALTER TABLE transactions ADD COLUMN currency_code TEXT; is fast and safe on Postgres 11 and later — a constant default is stored in the table's catalog metadata rather than written into every existing row, so the operation doesn't rewrite the table and the ACCESS EXCLUSIVE lock it briefly takes is genuinely brief. 

The danger is NOT NULL on an existing column, or a column being added NOT NULL without a default the engine can apply catalog-side. Historically, that forces Postgres to scan every row under an ACCESS EXCLUSIVE lock to verify nothing violates the constraint — on a transaction table with tens of millions of rows, that's minutes of every read and write queuing behind the migration. The safe sequence breaks the check into two steps with two different lock levels: 

-- Step 1: add the constraint unvalidated — brief lock, doesn't scan existing rows 

  ADD CONSTRAINT currency_code_not_null CHECK (currency_code IS NOT NULL) NOT VALID; 

-- Step 2: validate separately — full table scan, but only a SHARE UPDATE 

-- EXCLUSIVE lock, which allows concurrent reads and writes to continue 

ALTER TABLE transactions VALIDATE CONSTRAINT currency_code_not_null; 

-- Step 3: now genuinely instant, because the CHECK already proves it 

ALTER TABLE transactions ALTER COLUMN currency_code SET NOT NULL; 

Postgres 18 adds a more direct path — ADD COLUMN ... NOT NULL NOT VALID natively — but the three-step CHECK pattern above is worth knowing regardless of version, both because it's what most production databases are still running and because it makes explicit what's actually happening: the expensive part (the scan) and the expensive lock (ACCESS EXCLUSIVE) don't have to happen together. 

Indexes and keys: concurrently, or not at all, on a live table 

CREATE INDEX without CONCURRENTLY takes a lock that blocks all writes for the entire build — minutes on a large table, long enough to matter on anything taking continuous transaction volume. CREATE INDEX CONCURRENTLY builds the index in a way that permits concurrent writes throughout, at the cost of roughly doubling the build time and a real caveat worth planning for: it isn't guaranteed to succeed, and a failed concurrent build leaves an invalid index behind that has to be dropped and retried manually rather than automatically rolled back. 

Primary and unique keys deserve the same two-step treatment as the NOT NULL case, because ADD CONSTRAINT ... PRIMARY KEY on its own builds the backing index under a lock that blocks everything: 

CREATE UNIQUE INDEX CONCURRENTLY transactions_external_ref_key 

  ADD CONSTRAINT transactions_external_ref_pkey 

  PRIMARY KEY USING INDEX transactions_external_ref_key; 

The first statement does the expensive work without blocking anything. The second attaches the constraint to an index that already exists, which is fast enough that the brief lock it does take is rarely worth worrying about. 

Renaming or retyping a column: there is no safe single step 

A rename or a type change has no version of "just do it carefully" — any direct approach either breaks currently-deployed application code mid-migration or rewrites the entire table under an exclusive lock. The only safe path is the full expand-contract sequence, run as independent deploys: 

Expand: add the new column alongside the old one. 

Dual-write: deploy application code that writes both columns on every mutation, reads from the old one still. 

Backfill: populate the new column for existing rows, in bounded batches — a single UPDATE touching the whole table is the same long-lock problem in a different shape, and on a replicated setup, it's also a replication-lag problem. Chunk it, with a pause between batches: 

    UPDATE transactions SET settlement_currency = currency_code 

      AND id IN (SELECT id FROM transactions WHERE settlement_currency IS NULL LIMIT batch_size); 

    GET DIAGNOSTICS rows_updated = ROW_COUNT; 

Cut over: deploy application code that reads from the new column. 

Contract: once nothing reads or writes the old column, drop it. 

Five steps sounds like overhead for what a RENAME COLUMN would do in one statement. It's the overhead that guarantees every one of those five deploys can be rolled back independently — a failed step 4 rolls back to a code deploy that still works against the dual-written state from step 2, rather than to a schema that no longer matches what any deployed version of the application expects. 

The rollback plan is part of the migration, not an afterthought 

Every step above needs its own reverse, decided before the migration runs, not improvised if it goes wrong: an added column's rollback is dropping it; a dual-write deploy's rollback is reverting to the previous code, which still works because the old column is untouched. Set lock_timeout on any DDL statement in production — a few seconds is typical — so a migration that would otherwise queue behind a long-running query fails fast and gets retried, instead of silently blocking every other transaction on the table for however long that query takes to finish. On a core banking table, a migration that fails loudly in seconds is a minor annoyance. One that succeeds by blocking real transaction volume for minutes is an outage with a dollar figure attached to it — which is the actual reason none of this is optional, whatever the migration tool's default behavior suggests is fine. 

For the rare case that genuinely needs a full table rewrite — a column type change with no incremental path — pg_repack rewrites a table's physical storage without holding the long exclusive lock a plain ALTER TABLE ... TYPE would. It's a heavier tool than anything above, and worth reaching for only after confirming the expand-contract sequence genuinely can't get you there, not as a default. 

Zero-Downtime Schema Migrations for Core Banking Tables 

Expand-contract migration patterns, backward-compatible schema changes, and rollback strategies for altering high-volume transaction tables without locking the system.

An "add a column" migration looks safe in every code review. What it does to a live table depends on which Postgres lock it takes.

Patterns That Survive Production 

Every caching tutorial treats staleness as a performance trade-off — how long can this data be wrong before someone notices, and does it matter. For most data, that's the right question. For an account balance, it's the wrong one, because the person who notices first is a customer deciding whether they can afford something, and "the cache was 40 seconds behind" is not a defense a regulator finds persuasive. This one's for the backend engineer choosing a caching strategy for balance-adjacent data, and the delivery lead who needs to understand why the "obvious" choice isn't always the safe one. 

A stale product recommendation is a missed opportunity. A stale account balance is a customer making a real financial decision on wrong information, and it sits close enough to disclosure and payment-services obligations — showing customers accurate, timely account information — that a systemic caching bug isn't a performance postmortem, it's the kind of control gap we've written about in the context of reconciliation and DORA operational resilience: not dramatic on its own, but exactly the sort of thing an auditor eventually asks "how did this happen, and for how long." 

That framing matters because it changes the actual engineering question. The question isn't "what's the fastest way to cache a balance." It's "what's the caching strategy whose failure mode is acceptable" — because every caching strategy fails eventually, and the two patterns below fail in different ways. 

Cache-aside: fast, resilient, and stale on a specific race 

Cache-aside is the pattern most Spring/Redis integrations reach for by default: check the cache, on a miss load from the database and populate the cache, and on a write, update the database and delete the cache key rather than update it. 

    public BigDecimal getBalance(UUID accountId) { 

        String cached = redis.opsForValue().get("balance:" + accountId); 

        if (cached != null) return new BigDecimal(cached); 

        BigDecimal balance = accountRepository.getBalance(accountId); 

        redis.opsForValue().set("balance:" + accountId, balance.toString(), Duration.ofSeconds(30)); 

    public void applyTransaction(UUID accountId, BigDecimal delta) { 

        accountRepository.adjustBalance(accountId, delta); // DB commit first 

        redis.delete("balance:" + accountId);               // then invalidate 

 The ordering — commit the database write, then delete the cache key, never the reverse — is the part worth treating as non-negotiable rather than a style preference. Deleting first opens a window where a concurrent read can miss, reload the still-old value from the database, and write it back into the cache after your delete completes — leaving a stale balance cached with nothing left to correct it until the TTL expires. 

Even with the correct ordering, cache-aside has one race left: a slow reader that started before the write, misses, and populates the cache with the old value after the delete already ran. This is bounded — the TTL puts a hard ceiling on how long the staleness can persist — but for a balance, "bounded by 30 seconds" is still 30 seconds a customer could be looking at the wrong number. For genuinely hot keys, the fix is the delayed double-delete: schedule a second delete a few hundred milliseconds after the first, on the assumption that any concurrent read racing the write will have finished by then. It adds a small amount of complexity for a real reduction in the exposure window. 

Write-through: always fresh, until it silently isn't 

Write-through avoids the race entirely by writing the new value to the cache and the database as part of the same operation, so a read never sees a gap between "old value still cached" and "new value not yet cached" — there's no window for a stale re-population to land in. 

public void applyTransactionWriteThrough(UUID accountId, BigDecimal delta) { 

    BigDecimal newBalance = accountRepository.adjustBalance(accountId, delta); 

        redis.opsForValue().set("balance:" + accountId, newBalance.toString(), Duration.ofSeconds(30)); 

    } catch (RedisConnectionFailureException e) { 

        redis.delete("balance:" + accountId); // fail safe: force a DB read next time 

        log.warn("Cache write failed for account {}; forcing fallthrough", accountId, e); 

The failure mode that matters here is the one most write-through examples skip: the database commit succeeds and the cache write fails — a network blip, a Redis node mid-failover. Unlike cache-aside, there's no natural self-healing here; nothing is going to notice the mismatch and correct it until the TTL expires on its own. The catch block above is the part that actually matters: on a cache-write failure, delete the key rather than leaving whatever was there — silently serving the previous balance until TTL is a materially worse failure than a temporary cache miss that falls through to the database. Treat a write-through cache-write failure as "we don't know what's in here anymore," not as a warning to log and move past. 

The decision that actually matters: which failure would you rather explain 

Neither pattern is universally correct, and picking one without naming the failure mode you're accepting is how a team ends up defending an incident after the fact instead of designing around it beforehand. 

Cache-aside with a short TTL and delete-on-write is the right default for balance-adjacent data specifically because its worst case is well-understood and bounded: a brief, TTL-limited staleness window, self-correcting even if the corrective code has a bug, because the TTL always wins eventually. It's also simpler to reason about under partial failure — a Redis outage degrades gracefully into "every read hits the database," which is slower, not wrong. 

Write-through earns its place where read latency on a cold cache is itself unacceptable — a high-frequency trading or fraud-scoring path where even a single database round-trip on a miss is too slow — and where the team is willing to build the explicit fail-safe invalidation path above, rather than trusting the happy path. Without that fail-safe, write-through's worst case is unbounded and silent, which is the opposite of what you want from a control that a regulator might eventually ask about. 

For most balance-display use cases, the honest answer is that cache-aside's bounded, self-correcting failure mode is the easier one to stand behind in an incident review, and the latency it costs — one extra database round-trip on a cache miss — is a price worth paying for not having to explain why a cache silently disagreed with the ledger for an hour. Reach for write-through only when the latency requirement genuinely forces it, and never without the explicit cache-write-failure handling that keeps its failure mode bounded too. 

Redis Caching in Financial Systems 

Cache invalidation strategies for balance-adjacent data, write-through vs. cache-aside tradeoffs, and the specific failure modes that turn a cache bug into a customer-facing compliance incident.

A stale recommendation is a missed opportunity. A stale account balance is a compliance question. Here's the cache-aside vs. write-through call.

When a Stale Balance Is a Compliance Problem 

Every ledger I've worked on eventually gets the same question from an auditor: "show me exactly how this balance came to be, in order, with nothing missing." A system that only stores current balances can't answer that — it can show you where the number landed, not how it got there. Event sourcing exists for exactly this question, and CQRS is what keeps answering it fast from making every other query slow. This is a walkthrough of building both correctly, including the part where "just use Kafka as your event store" needs a caveat most tutorials skip. 

Why a balance column is the wrong source of truth 

A conventional ledger table stores current balance and overwrites it on every transaction. That's fine for reading a balance quickly and terrible for proving how it was reached — the history of how you got there is gone the moment the update commits, unless you've separately built an audit log to shadow it. Event sourcing inverts the model: the append-only sequence of events — FundsDeposited, FundsWithdrawn, TransferInitiated — is the source of truth. A balance isn't stored; it's derived, by replaying events in order. Nothing is ever updated or deleted. That single design choice is what makes the audit question trivial to answer instead of expensive to reconstruct. 

CQRS is what keeps that design fast in practice. The write side (the event store) only ever appends. The read side (a projection, optimized for the query you actually need — "what's this account's balance right now") is built by consuming those events and materializing them into a queryable shape. Splitting the two means the write path stays simple and the read path can be denormalized however a dashboard or a statement generator needs it, without either constraining the other. 

public sealed interface AccountEvent permits FundsDeposited, FundsWithdrawn { 

    UUID accountId, long version, Instant occurredAt, BigDecimal amount) implements AccountEvent {} 

version is the field that matters most and gets skipped most often in tutorials: a strictly increasing sequence number per aggregate (per account, here), starting at 1. It's what makes optimistic concurrency possible — and optimistic concurrency is what stops two concurrent withdrawals from silently corrupting the same account's history. 

Why the event store has to be a database, not a raw Kafka topic 

This is the caveat worth being explicit about, because "use Kafka as your event store" is common advice that glosses over something Kafka doesn't do: it has no native way to reject a conditional append. A Kafka topic will happily accept two producers both writing "version 6" for the same account, in whichever order they arrive — there's no broker-side check equivalent to a unique constraint. For a ledger, that gap is exactly the race condition that produces a corrupted, unreconstructable balance history. 

The pattern that actually holds is the same one we've written about for Kafka payment pipelines: the database is the real source of truth for the atomic append, with a unique constraint enforcing the optimistic concurrency check; Kafka's role is distributing those events out to projections and other services, not arbitrating who wins the write. 

       uniqueConstraints = @UniqueConstraint(columnNames = {"account_id", "version"})) 

    @Id @GeneratedValue private UUID id; 

    private String payload; // serialized event 

public void append(UUID accountId, long expectedVersion, AccountEvent event) { 

            new AccountEventEntity(accountId, expectedVersion, event)); 

        outboxRepository.save(new OutboxEntry(accountId, serialize(event))); // same DB transaction 

    } catch (DataIntegrityViolationException e) { 

        throw new ConcurrentModificationException( 

            "Account " + accountId + " was modified concurrently — reload and retry"); 

The unique constraint on (account_id, version) is what actually enforces the guarantee. A caller that read the account at version 5 and tries to append version 6 while someone else's version-6 write already landed gets a constraint violation, not a silently corrupted sequence — the same defense-in-depth pattern we've used for idempotency, applied here to append ordering instead of duplicate requests. The outbox row written in the same transaction is what gets relayed to Kafka via CDC, exactly as described in our piece on Kafka transactional pipelines — so events reach downstream projections reliably without ever making Kafka responsible for the concurrency check it isn't built to make. 

Snapshotting: replaying history without replaying all of it 

Rebuilding a balance by replaying every event since account opening works fine for a new account and gets slow for one with ten years and forty thousand transactions behind it. A snapshot is a periodic materialization of an aggregate's state at a given version, so a rebuild only has to replay events since the snapshot: 

    Optional<Snapshot> snapshot = snapshotRepository.findLatest(accountId); 

    long fromVersion = snapshot.map(Snapshot::version).orElse(0L); 

    Account account = snapshot.map(Snapshot::toAccount).orElseGet(Account::empty); 

    eventRepository.findByAccountIdAndVersionGreaterThan(accountId, fromVersion) 

    accountRepository.findModifiedSince(LAST_SNAPSHOT_RUN).forEach(account -> { 

        if (account.version() % SNAPSHOT_FREQUENCY == 0) { 

            snapshotRepository.save(Snapshot.of(account)); 

Snapshots are a performance optimization, never a replacement for the event log — they're disposable and rebuildable from events at any time. If a snapshot is ever found to be wrong (a bug in apply logic, say), deleting it and rebuilding from events is always safe. That property — snapshots are cache, events are truth — is the whole reason this design stays audit-grade even after snapshotting is added. 

Rebuilding the read model from the event stream 

The projection that actually answers "what's this account's balance" lives on the Kafka-consuming read side, built from the same events the write-side event store produced: 

@KafkaListener(topics = "account-events", groupId = "balance-projector") 

public void project(AccountEvent event) { 

    BalanceView view = balanceViewRepository.findByAccountId(event.accountId()) 

        .orElseGet(() -> BalanceView.empty(event.accountId())); 

    view.apply(event); // same domain logic as the write-side aggregate 

 This consumer can be dropped and rebuilt from the beginning of the topic at any time — replaying it against the full event history is how you fix a bug in the projection logic, or stand up a new read model (a monthly statement view, a regulator-facing export) without touching the write side at all. That's the actual payoff of the CQRS split: the read model is disposable and the write model isn't, which is the opposite of how a conventional balance-column ledger is forced to treat both. 

What makes this audit-grade, specifically 

Immutability has to be enforced, not just assumed by convention — a database role with INSERT-only privilege on the events table, no UPDATE or DELETE grant at all, is what actually stops a well-meaning engineer's one-off data fix from quietly rewriting history. Replay has to be deterministic — an apply() function with no external dependency, no current-time lookup, nothing that could produce a different result run twice against the same event sequence. And the event schema itself needs the same evolution discipline as any other long-lived contract: additive changes only, versioned event types, because an event written five years ago has to still deserialize and replay correctly today. None of that is exotic. It's the same discipline that makes any audit trail trustworthy — applied here to the ledger itself, not bolted onto it afterward.

Event Sourcing for Auditable Ledgers

Implementing an event-sourced ledger with CQRS in Java — event store design, snapshotting, and rebuilding balances from history for audit-grade transaction records.

A balance column shows where a number landed, not how it got there. Here's how to build an event-sourced, CQRS ledger in Java, audit-ready.

Building a CQRS Transaction History Store 

"Kafka guarantees exactly-once" is the sentence that gets a payments team into trouble, because it's true in exactly the narrow sense that matters least to the people repeating it. Kafka can guarantee exactly-once processing for a read-process-write sequence entirely within its own boundary. The moment that sequence touches a database — which a payment pipeline always does — the guarantee needs help it doesn't come with automatically. This is a walkthrough of what Kafka's transactional API actually does, what it doesn't, and where the seam is that a payments team needs to close itself. 

Why "at-least-once" is the honest default, and why it produces real duplicates 

A Kafka producer, configured with nothing beyond the basics, gives you at-least-once delivery. A broker acknowledgment gets lost on the way back to the producer, the producer retries, and the broker — having already written the first attempt — now has two copies of the same logical event. A consumer has the mirror problem: it processes a batch, crashes or gets rebalanced before committing its offset, and the next consumer instance picks up from the last committed offset, reprocessing records that were already handled. 

For a payment-initiated event flowing through a pipeline that eventually calls a settlement API or writes a ledger entry, either of those duplicates is a double-charge or a double-posted transaction, not a cosmetic log artifact. This is the exact failure class idempotency keys exist to catch at the API boundary — we've covered that pattern in detail elsewhere. What this piece is about is closing the same gap one layer earlier, inside the pipeline itself, so the duplicate never reaches the point where an idempotency key has to catch it. 

Idempotent producers solve one specific problem, not the general one 

Setting enable.idempotence=true (the default in modern Kafka clients) assigns the producer a Producer ID and attaches a monotonically increasing sequence number to every message sent to a given partition. The broker deduplicates on (PID, sequence number), so a producer retry after a lost acknowledgment doesn't create a second copy — the broker recognizes the sequence number it already has and discards the retry. 

That's a real guarantee, and it's necessary. It's also narrow: it protects against producer-side retries to a single partition. It says nothing about a consumer reprocessing a batch after a crash, and nothing about atomicity across multiple partitions or topics — which is exactly what a payment pipeline usually needs, because "consume the payment-initiated event, write the ledger entry, produce the payment-settled event" touches more than one topic. 

Transactions: atomicity across the whole read-process-write sequence 

Kafka's transactional API is what closes the rest of the gap. Configuring a transactional.id on the producer lets it group multiple sends — potentially across several topics and partitions — into a single atomic unit, and critically, lets it include the consumer's offset commit inside that same transaction. Either everything in the transaction becomes visible to downstream consumers, or none of it does. 

    public ProducerFactory<String, PaymentEvent> producerFactory() { 

        Map<String, Object> props = new HashMap<>(); 

        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers); 

        props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true); 

        props.put(ProducerConfig.ACKS_CONFIG, "all"); 

        // Unique per instance — Spring Boot appends an instance suffix 

        // automatically when you set transaction-id-prefix. 

        props.put(ProducerConfig.TRANSACTIONAL_ID_CONFIG, "payment-pipeline-tx-"); 

        DefaultKafkaProducerFactory<String, PaymentEvent> factory = 

            new DefaultKafkaProducerFactory<>(props); 

        factory.setTransactionIdPrefix("payment-pipeline-tx-"); 

    public KafkaTransactionManager<String, PaymentEvent> kafkaTransactionManager( 

            ProducerFactory<String, PaymentEvent> producerFactory) { 

        return new KafkaTransactionManager<>(producerFactory); 

 With Spring Boot, most of this collapses to a single property — spring.kafka.producer.transaction-id-prefix — and Spring auto-configures the KafkaTransactionManager and wires it into the listener container. The transactional.id has to be unique per producer instance across your fleet; reusing it across instances is what causes a producer to fence itself off, which is the mechanism working correctly, not a bug, but confusing the first time it happens in production. 

The consumer side: committing offsets inside the transaction, not after it 

This is the part that's easy to get wrong even with transactions enabled: committing the consumer offset as a separate step after the transaction commits reopens the exact gap transactions exist to close. If the process crashes between the Kafka transaction commit and the offset commit, the next consumer instance reprocesses the same batch — the transaction protected the write, but not the read-process-write sequence as a whole. 

The fix is producer.sendOffsetsToTransaction(), which folds the offset commit into the same atomic transaction as the outbound sends: 

Exactly-Once Semantics in Kafka Payment Pipelines 

A code-level walkthrough of Kafka transactions, producer idempotence, and consumer offset commits for payment event pipelines where "probably delivered once" isn't good enough.

Kafka guarantees exactly-once is true in a narrower sense than most payment teams assume. Here's what transactions cover, and where the gap still is

All News

Categories

All News

Categories

Do you want to read more?

Subscribe now for our bimonthly newsletter!