The question to answer
Can a consumer recover from a crash after a database commit without applying the same business effect twice?
Proposed scope
Build a public demonstration with synthetic transaction events. This is a proposed independent project, not a release of a bank’s implementation.
Constraints to make explicit
- Stable event identifiers and versioned payloads.
- Database effects and the deduplication record share one transaction.
- Consumer progress is committed after durable persistence; ordering is assessed separately.
Your contribution
To complete: identify what you personally designed, implemented and verified, the project version, and any collaborators’ contributions.
Architecture & boundaries
Conceptual starting point, not an implemented architecture.
To complete: replace this overview with the implemented components, data flow, persistence boundaries and failure paths. Link the diagram source to the tested commit.
Engineering decisions
Deduplication boundary
Compare a unique destination key with a transactional event ledger. Explain which business effects the chosen approach covers.
Decision record to add
Chosen approach · alternative considered · trade-off · supporting code or experiment.
Recovery and ordering
Describe offset commits, concurrent consumers, late events and the rule preventing an older event from overwriting newer state.
Decision record to add
Chosen approach · alternative considered · trade-off · supporting code or experiment.
Retention
Choose a deduplication retention window and show what happens when a replay exceeds it.
Decision record to add
Chosen approach · alternative considered · trade-off · supporting code or experiment.
How to verify it
Planned scenarios — no test outcomes recorded yet
| Scenario | Acceptance criterion | Evidence to attach |
|---|---|---|
| Crash after database commit, before offset commit | Replay leaves the intended business state unchanged. | Attach a reproducible failure-injection test and database assertions. |
| Duplicate event delivered concurrently | Exactly one intended database effect is persisted within the documented transaction boundary. | Attach the constraint/transaction test output. |
| Older event arrives after a newer event | The selected version policy prevents stale state from winning. | Attach input sequence and expected/actual rows. |
Inspect the evidence
Repository
Not attached
Add a public repository with a README, pinned versions and synthetic fixtures.
Run instructions
Not attached
Add commands to start Kafka/Postgres, seed events and execute the recovery scenario.
Test report
Not attached
Link the exact CI run or versioned report for the failure scenarios.
Results
Not attached
Attach SQL assertions, measured results and the commit tested.
Reproduction record to add: repository URL, exact commit, tool versions, setup commands, data-generation seed, expected output and the command used to run verification.
Results & measurements
No measurements have been published. Fill in the baseline, observed result, workload and method for each metric; attach raw evidence.
Unique durable effects
Compare expected event identities with persisted effects.
Baseline: not measured · Result: not measured · Evidence: not attached
Recovery time
Measure from injected failure to restored progress; document workload and hardware.
Baseline: not measured · Result: not measured · Evidence: not attached
Throughput and latency
Record event rate and p50/p95 latency, including failures and database settings.
Baseline: not measured · Result: not measured · Evidence: not attached
Limitations & next steps
The proposed guarantee is a database-local idempotent effect. External APIs, notifications and arbitrary sinks require their own coordination. No exactly-once guarantee is claimed before implementation and testing.
To complete: list unsupported cases, remaining risks, what the results do not establish, and the next improvement you would make.
Related experience & writing
Read the professional experience summary →
Read the related engineering article →
Professional experience provides context; it is separate from this proposed public demonstration.