BuzzKit: a self-hosted notification orchestration layer for iOS push
The open source notification orchestration layer
At a glance
- What is it?
- BuzzKit is an AGPL-3.0 TypeScript monorepo that puts subscriber management, targeting, preferences, scheduling, workflows, retries and delivery receipts behind one API and one dashboard. It ships iOS push today, runs on Cloudflare Workers with PostgreSQL and Tinybird, and its self-hosting guide is still marked as coming soon.
- Who is it for?
- Adopt BuzzKit if you are building an iOS app, you are comfortable running a Cloudflare Worker with PostgreSQL and Tinybird, and you want subscriber state and workflow logic in your own infrastructure rather than in a vendor account. Do not adopt it if you need Android, email or SMS now, since the README lists all three as unchecked roadmap items, or if you want a managed service with a published self-hosting guide, because that guide is still only promised.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 54 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- buzzkit-dev/buzzkit396 ★ · +49
| Repository | 2026-09-17 | 2026-11-21 |
|---|---|---|
| buzzkit-dev/buzzkit | 347 | 396 |
49 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem BuzzKit takes on: notification state scattered across providers
Most teams do not start with a notification system. They start with a push call inside the signup handler, a device token column on the users table, and a second push call inside the order status job. Within a few months, the questions that matter are not about sending. They are about who is subscribed, which device belongs to which user after a reinstall, which of three events should collapse into one message, and what happened when a provider returned an error at 3am.
BuzzKit positions itself as the layer that holds that state. The README describes it as an orchestration layer where you bring the keys for your providers and get subscriber management, targeting, preferences, scheduling, workflows, retries and delivery receipts through one API and one dashboard. The intended shape is integrate once, then drive everything from events: the SDK keeps users and devices in sync, your app and backend report what happened, and workflows decide what to send and when.
That framing tells you who it is for. It is for a product team that has already decided notifications are a first-class part of the product, has an iOS client, and would rather own the orchestration than rent it. It is not aimed at a script that fires one push when a build finishes.
Architecture: a Cloudflare Worker, PostgreSQL, Tinybird, and a shared schema package
The repository is a Bun and Turborepo monorepo. The top level splits into apps and packages. Under apps, the API is a Cloudflare Worker, web is the dashboard, marketing serves buzzkit.dev, and docs serves docs.buzzkit.dev. Under packages, buzzkit is the server SDK, schema holds the grammars that the API and the dashboard both validate (workflows, sources, imports), database holds the Drizzle schema and migrations, auth is the BetterAuth configuration, eden is the typed API client the dashboard uses, observability covers logging and tracing, tinybird holds the event stream as code, and ui is the design system.
Two details in that layout are worth pausing on. First, packages/schema exists so that the dashboard and the API validate workflows against the same grammar. A workflow editor that accepts a shape the API rejects is a common source of confusion in tools like this, and putting the grammar in a shared package is a direct answer to it. Second, packages/tinybird treats the event stream as code. Tinybird is a ClickHouse-based analytics service, and the docker-compose file runs tinybirdco/tinybird-local on port 7181 with a volume mounted at /var/lib/clickhouse. Delivery receipts and event data flow into that store rather than into PostgreSQL.
That split has a consequence for operators. Transactional state (subscribers, devices, preferences, workflows) lives in PostgreSQL, while event history lives in Tinybird. The README gives no schema for either, so how far back receipts are queryable is something you would have to determine from the code or the documentation site.
The iOS SDK is not in this repository. It lives in buzzkit-dev/buzzkit-ios, which means the client half of the integration is versioned separately from the server half.
Installing BuzzKit locally with Bun and Docker
The README's Development section is the only installation path it documents. It requires Bun and Docker. The first command installs workspace dependencies, and the second starts PostgreSQL and Tinybird Local in containers.
bun install
bun db:upAfter that, you copy two example environment files, one for the API and one for the dashboard.
cp apps/api/.dev.vars.example apps/api/.dev.vars
cp apps/web/.dev.vars.example apps/web/.dev.varsBefore the first start, the README says to set BETTER_AUTH_SECRET, CREDENTIAL_MASTER_KEY_V1 and SQIDS_ALPHABET in the API's .dev.vars, and that the example file explains how to generate each value. Then you run the database migrations, push the Tinybird resources, and start everything.
bun run --cwd packages/database db:migrate
bun run --cwd packages/tinybird push
bun devThe README notes that the Tinybird push must be run once for every fresh container, because that is what loads its event tables and endpoints. That is a step people will forget when they recreate volumes, and the failure will look like missing analytics rather than a broken start.
When it is up, the API listens on http://localhost:8790 with an OpenAPI reference at /swagger, the dashboard on http://localhost:5180, marketing on http://localhost:5181, and docs on http://localhost:5182. The /swagger route is the fastest way to see what the API actually exposes, since the README does not enumerate endpoints.
The self-hosting story is the weakest part of the pitch
BuzzKit's headline claim is that you can use it at buzzkit.dev or self-host the same code. The second half of that claim is not yet documented. The Self-Hosting section says a complete guide is coming soon, and that for now deployments require a Cloudflare account for Workers, KV, Queues, Durable Objects and Hyperdrive, together with PostgreSQL and Tinybird. It adds that the team plans to simplify this setup in future releases.
Read that list as a deployment constraint, not a footnote. Five Cloudflare products plus two data systems is a lot of surface area for a team whose actual goal is sending push notifications. The local docker-compose file covers PostgreSQL and Tinybird only; KV, Queues, Durable Objects and Hyperdrive have no local equivalent in the repository, so the path from a working local checkout to a working deployment runs through Cloudflare configuration that the README does not walk you through.
There is a second limitation in the same area. The README does not document rollback, migration reversal, or what happens to in-flight workflows during a deploy. Since workflows are stored state that a Worker evaluates, a bad deploy is not just a code problem. Anyone evaluating BuzzKit for production should treat that as an open question to answer from the code before committing.
Finally, the project describes itself as still in beta and limits pull requests to core contributors, with issues as the preferred channel. That is a reasonable posture for an early project, but it means you cannot upstream a fix yourself.
What BuzzKit does not do yet, and when to pick something else
The roadmap is explicit. BuzzKit supports iOS push today. Android with FCM, email through your own sending provider, SMS, web push, in-app messaging, and A/B experiments on messages and workflow steps are all unchecked. The topics list on the repository mentions email notifications and push notifications, but the README is clear that email and SMS are planned connectors rather than shipped ones.
So the honest comparison is against whatever you would otherwise use for iOS push. One real alternative is a hosted notification API that already covers iOS, Android, web and email behind a single endpoint. The difference in approach is where the state lives. With a hosted API, your subscriber records and delivery history sit in the vendor's system, and you get multi-channel coverage on day one without running a Worker or a ClickHouse-backed event store. With BuzzKit, you run the Cloudflare Worker, PostgreSQL and Tinybird yourself, and in exchange the subscriber graph, preferences and workflow definitions are yours, queryable in your own database.
A second alternative is to skip orchestration entirely and call the provider SDK from your backend, keeping device tokens in your existing users table. That is genuinely simpler for a small number of notification types, and it avoids the Cloudflare footprint. It stops being simpler the moment you need per-user preferences, scheduling, retries with backoff, or a record of what was delivered. The decision point is not scale, it is whether notification logic has started to spread across more than one service.
If you need SMS this quarter, BuzzKit is the wrong tool today regardless of how the architecture appeals to you.
Licence and upgrade cost under AGPL-3.0
The core is licensed under the GNU Affero General Public License Version 3, and package.json declares AGPL-3.0-only. The AGPL's defining feature compared with the GPL is the network clause: if you run modified software and let users interact with it over a network, the source of your modifications has to be offered to those users. For a self-hosted notification backend that your own app talks to, whether that clause reaches you depends on facts about your deployment and your modifications, so treat this as a question for your own counsel rather than something the README settles.
What the repository does show is that the licence covers the whole monorepo: the API, the dashboard, the SDK, the schema package and the UI design system all sit under the same top-level licence. There is no separate permissive SDK licence mentioned.
Upgrade cost is harder to judge because the repository has no published GitHub releases. The tooling is in place: changesets is configured, with sdk:version and sdk:release scripts in package.json, and the SDK publishes through packages/buzzkit. That suggests the SDK is versioned and published independently of the apps. The practical consequence for an adopter is that the server SDK can move ahead of the Worker and dashboard, so pinning the SDK version and reading its changelog is the sane default. The README does not describe a support window or a compatibility policy between SDK versions and the API, so pinning is a precaution rather than a documented requirement.
Editorial conclusion
Adopt BuzzKit if you are building an iOS app, you are comfortable running a Cloudflare Worker with PostgreSQL and Tinybird, and you want subscriber state and workflow logic in your own infrastructure rather than in a vendor account. Do not adopt it if you need Android, email or SMS now, since the README lists all three as unchecked roadmap items, or if you want a managed service with a published self-hosting guide, because that guide is still only promised. Before committing, verify that you can generate BETTER_AUTH_SECRET, CREDENTIAL_MASTER_KEY_V1 and SQIDS_ALPHABET as the example .dev.vars file describes, and confirm that your Cloudflare plan covers Workers, KV, Queues, Durable Objects and Hyperdrive.
Frequently asked questions
What is BuzzKit and what does it do?
BuzzKit is an open source orchestration layer for notifications. You bring the keys for your providers, and it gives you subscriber management, targeting, preferences, scheduling, workflows, retries and delivery receipts through one API and one dashboard. It supports iOS push today, with Android, email and SMS listed as planned connectors.
How do I install and run BuzzKit locally?
You need Bun and Docker. Run bun install, then bun db:up to start PostgreSQL and Tinybird Local, copy the two .dev.vars.example files, set BETTER_AUTH_SECRET, CREDENTIAL_MASTER_KEY_V1 and SQIDS_ALPHABET in the API's .dev.vars, run the database migrate and Tinybird push commands, and start everything with bun dev.
Can I self-host BuzzKit without Cloudflare?
The README does not offer that option. It states that deployments require a Cloudflare account for Workers, KV, Queues, Durable Objects and Hyperdrive, together with PostgreSQL and Tinybird, and that a complete self-hosting guide is coming soon.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/buzzkit-dev-buzzkit)Star history chart for your README
[](https://hysenlabs.com/projects/buzzkit-dev-buzzkit)Was this useful?