Architecture & Guarantees

The Store-Before-Ack Guarantee

The fundamental engineering principle behind Bunnylynk is Store-Before-Ack:

Definition: No incoming HTTP webhook request is acknowledged with an HTTP 2xx response until the full payload and headers are committed to durable, replicated non-volatile storage.

       +-----------------+
       | Webhook Sender  |
       +--------+--------+
                | 1. HTTP POST Webhook
                v
       +--------+--------+
       | Ingestion Edge  |
       +--------+--------+
                | 2. Sync Durable Write
                v
       +--------+--------+
       | Replicated DB   |
       +--------+--------+
                | 3. Write Confirmed
                v
       +--------+--------+
       | 200 OK to Sender|
       +--------+--------+
                | 4. Async Dispatch
                v
       +--------+--------+
       | Your Destination|
       +-----------------+

Why this matters

Many lightweight proxies or serverless functions ingest webhooks by placing them in an in-memory queue or buffer before acknowledging the caller. If that node crashes, crashes during a redeployment, or experiences high load, in-memory payloads disappear forever.

By writing to disk first:

If your destination application is completely offline, the event is securely preserved in Bunnylynk.
If an entire cloud region experiences an outage, queued webhooks are not lost.
Senders receive an ultra-fast response (typically < 20ms), preventing sender timeout cancellations.

System Components

Bunnylynk is composed of four primary decoupled subsystems:

1. Ingestion Gateway (`apps/gateway`)

A hyper-efficient, minimal-footprint edge server deployed close to webhook senders worldwide. Its sole responsibility is:

TLS termination and IP verification
Payload size validation (up to 10MB per event)
Fast durable persistence into the events ledger
Immediate HTTP 202 Accepted response

2. Dispatch & Execution Worker

A distributed background scheduling engine responsible for:

Evaluating connection rules (filtering, transformations, rate limiting)
Dispatching HTTP POST requests to configured destinations
Tracking execution timing, status codes, and response bodies
Scheduling exponential backoffs upon receiving 4xx (like 429) or 5xx responses

3. Management & Control Plane API (`apps/api`)

A RESTful API offering complete programmatic control over:

Sources, Destinations, Connections, and Rules
Multi-tenant RBAC and scoped API authentication
Project workspace isolation and audit logs

4. Live Dashboard (`apps/web`)

A responsive web application offering real-time event streaming, payload inspectors, search/filtering, and one-click manual replays.

Delivery Guarantees Matrix

Guarantee	Level	Explanation
Durability	At-Least-Once	Once ingested, an event is never lost. If an attempt encounters network partition, it will be retried.
Ordering	Configurable FIFO	By default, connections can enforce FIFO delivery per source key to prevent race conditions.
Idempotency	Deduplication Key	Senders passing event IDs or idempotency keys are deduplicated within configurable sliding windows.
Latency	< 25ms Ingestion	Ingestion p99 latency stays under 25ms regardless of destination downstream performance.

Continue to Installation & Setup to learn how to configure your project.

Quickstart Installation & Setup