29,989
events accepted
0 failed29k+ events · open source
Every notification,
accounted for.
Herald is an open-source notification system built on a transactional outbox. One commit writes the event, its timeline, and the outbox. Then every delivery is tracked to a terminal state. 29,989 events in, zero lost.
Free and open source. One command to run.
How it works
One promise,
One promise,
three mechanisms.
Each mechanism exists for one reason: a notification must never silently disappear.
01 / Commit
Accept first.
Accept first.
Decide later.
The event, its timeline, and the intent to publish commit in a single Postgres statement. Your API returns 202 only after the work is durable.
- One SQL statement, three writes
- 202 after the commit, never before
- The outbox is the recovery plan
one transactionPostgres
notificationsevent, recipient, policyinsert
notification_eventsappend-only timelineinsert
outboxpublish intentinsert
02 / Receipts
Numbers,
Numbers,
not adjectives.
Don't take our word for it: every figure on this page comes from a run you can repeat with one command.
- 29,989 events accepted in 10 minutes
- 0 failed requests at 50/s
- 4.10s from timeout to replay
backlog after 10 minutes3 runs
03 / Trace
The failure has
The failure has
a paper trail.
When a provider times out, you see the whole story (unknown, dead letter, replay, recovered) under one trace ID.
- Policy hash and channels considered
- Every attempt with error class and latency
- Inbox state and outbox state in one place
trace 6f3c21aa4.10s
acceptedcommit
fanout planned3 channels
push unknowndead letter
replay appliedsame ID
recovered1 item
Runs on the stack you already have.
NodePostgresKafkaRedisDockerMailpitGitHub
Receipts
Measured,
Measured,
not promised.
One 10-minute run on a 4-core laptop, not a cloud benchmark. Every number is reproducible from the repository.
0
accepted events lost
SIGKILL tested4.10s
timeout to replay
same IDAlso measured: 4.3M events/day · 71,052 deliveries · 11.6s p95 · 36s recovery after SIGKILL. Raw results ship with the repo.
Run it
Running beats
Running beats
reading.
Three setups, same guarantee. Pick the smallest one that proves it to you.
One command.
The smallest setup that shows the outbox and the trace end to end.
make demo- Postgres, Redis, Kafka, Mailpit
- API and one core worker
- A seeded notification you can trace
The real path.
The full topology: API, workers, and a dataset that behaves like production.
pnpm herald demo- API, core worker, 3 delivery workers
- 24 partitions per priority topic
- 2,200 seeded users and a paused campaign
Break it yourself.
Kill processes, replay dead letters, and check that nothing goes missing.
pnpm herald doctor- Capacity model and 10-minute runs
- Crash test with SIGKILL
- Trace API and dead-letter replay
Scope
Limits,
Limits,
written down.
Herald is a local demo shaped like production, not production itself. What is missing is listed here, not hidden.
Read the capacity model →One Postgres shard, one Kafka broker, one Redis
The demo keeps the dependency footprint small. It is not a claim about a multi-region deployment.
Push and SMS are deterministic mocks
Email goes to Mailpit. Push and SMS return scripted outcomes so the failure path is reproducible.
300M events/day is a design target, not a measurement
The measured ceiling is 4.3M events/day on the 4-core laptop used for the runs.
Local tables are not partitioned
Retention deletes in batches. Partitioning is the first change for a larger deployment.
Methods
How the numbers
How the numbers
were made.
The benchmark, the crash test, and the scenarios are all in the repository, with the raw results beside them.
throughput10 min
eventsaccepted29,989
requestsfailed0
replaytimeout to same ID4.10s
How the 10-minute ceiling was measured
Read the method →crash testSIGKILL
beforeaccepted712
lostno replay10
afteraccepted656
lostreplayed0
What survived SIGKILL
Read the run →campaigns2,200 users
queuedat pause1,000
deliveredsame pipeline955
resumenext batch400
Campaigns, retries, and the failure path
Read the scenarios →Stop losing
notifications quietly.
Run the demo, trace one notification, and check the receipts yourself.
Free and open source. MIT licensed.