Architecture

How one Cloudflare Worker serves the API, dashboard, site and docs, and why each resource exists.

EmitKit is one Cloudflare Worker (emitkit). It serves three hostnames, built from one Vite build and provisioned by one Alchemy stack.

                 ┌──────────────────────── Worker "emitkit" ─────────────────────────┐
 api.emitkit.com │ src/worker/router.ts ── public API (/v1/*, /api/v1/*), MCP (/mcp),│
 app.emitkit.com │   (host → surface)   ── Better Auth (/api/auth/*), oRPC (/rpc/*),  │
 emitkit.com     │                      ── static PWA (dist/client/app/**)           │
                 │                      ── static marketing (dist/client/www/**)     │
                 │ queue() ── push fan-out        scheduled() ── retention sweep      │
                 └─────┬──────────┬───────────────┬──────────────┬──────────────┬────┘
                       D1      Analytics Engine   Queue      Email Sending   Workers AI

Surfaces

src/worker/router.ts compares the request host with those three variables. Hashed build output under /assets/* bypasses the Worker (run_worker_first: ["/*", "!/assets/*"]). Other paths are mapped to the surface’s folder: /x → /app/x or /www/x, or …/index.html when the path has no extension. Unknown PWA routes fall back to the app shell, and unknown site routes get the prerendered 404 page.

Modules

Boundaries are enforced by oxlint.config.ts (no-restricted-imports): frontends never import backend code; src/server never imports adapters or UI; nothing uses deep relative imports.

Data

• D1 (migrations/): Better Auth tables (users, sessions, accounts, organizations, members, invitations, API keys, auth rate limits) and EmitKit tables (projects, channels, identities, aliases, idempotency receipts, push subscriptions, event tombstones, the event hot buffer).
• Workers Analytics Engine (emitkit_events): the event store. One data point per event; the layout is documented in src/server/events/event-store.ts. Retention is about 90 days and applied by the platform. Reads use the SQL API with a read-only account token that Alchemy mints (CF_ANALYTICS_TOKEN).
• Hot buffer: Analytics Engine makes a write queryable after roughly a minute, so every event is also written to the D1 event table for 25 hours. Feed reads merge both stores, deduplicated by id. The hourly cron trims it.
• Event value: money at the top level of an event’s metadata ({ "amount": 49, "currency": "EUR" }, rule in src/shared/event-value.ts) is extracted at ingest into its own columns: value_amount/value_currency in D1 (migration 0002 backfilled older rows), double3/blob13 in Analytics Engine (points written before that read as no value). The dashboard’s Revenue sums it without parsing JSON.
• Pulse (events.pulse): event counts and value sums in equal buckets (1 h × 24, 6 h × 28 or 1 day × 30), for the range and the one before it. Buckets that start within the last 24 hours come from the hot buffer (exact); older ones from Analytics Engine (SUM(_sample_interval), so sample-weighted estimates). Revenue uses the currency most valued events carry; other currencies are not added in.
• Events cannot be updated in Analytics Engine: deletions and identity erasure are applied at read time (event_tombstone, erased_identity).
• EVENT_STORE=d1 keeps all events in D1 for 90 days instead. It is used for local development and suits self-hosters who don’t need Analytics Engine.

Request flows

• Public API and MCP: src/worker/public-api.ts hands the Web Request to PublicHttp (src/server/public-api/router.ts) with HttpEffect.toWebHandlerWith, using the isolate’s app services. PublicHttp assigns the request id, rejects bodies over 1 MiB, then routes with Effect’s HttpRouter. MCP tool calls run the same endpoints in-process on a request built with HttpServerRequest.fromClientRequest.
• Ingest POST /v1/events: API key verified by Better Auth’s api-key plugin (hash lookup + 100 req/min limit) → idempotency claim (optional) → schema validation → channel get-or-create → identity alias resolution → write to event store → event.created on the queue when notify is true.
• Push: the queue consumer loads the organization’s push subscriptions that match the channel, sends RFC 8291 Web Push with VAPID (@pushforge/builder), and deletes subscriptions the push service reports gone.
• Dashboard: the PWA calls /rpc/* with its session cookie. Every procedure resolves the session’s active organization and checks membership. Nothing trusts an organization id sent by the client.
• Local dev sign-in: under pnpm dev, “Continue in local dev” on the sign-in page calls POST /api/auth/dev/sign-in (src/server/platform/dev-sign-in.ts, a small Better Auth plugin). It creates a session for dev@example.com, creating that user on first use. The endpoint is always registered, so auth.api types stay stable, but it answers 404 unless import.meta.env.DEV is true and APP_URL is a localhost host. Every build compiles import.meta.env.DEV to false. The Worker bundle still registers the endpoint, but it always answers 404, and the client bundle drops the button entirely. 08-dev-sign-in.spec.ts checks both halves. Better Auth’s testUtils plugin wasn’t used because its docs say to keep it out of the real auth config.

Effect

• Every service is a Context.Service with a static layer. Failures are tagged errors (src/server/errors.ts) that adapters map to HTTP/oRPC errors.
• src/worker/runtime.ts builds the application Layer once per isolate. If that build stalls or fails, the next request rebuilds it.
• Background work uses structured concurrency (Effect.forEach with bounded concurrency for queue batches and push fan-out).

oRPC evaluation

The dashboard contract (src/shared/rpc/contract.ts) uses oRPC with @orpc/experimental-effect: Effect Schema contracts, .effect() generator handlers, and services provided through effect/context. The public API does not use oRPC’s OpenAPI handler. Reproducing openapi.json exactly would mean overriding the status codes, headers (rate limit, idempotency replay, WWW-Authenticate) and error bodies of every operation. Instead the checked-in spec is served verbatim.

Effect HTTP for the public API

The public API and MCP run on effect/unstable/http: HttpRouter for routing, HttpServerRequest/HttpServerResponse in the endpoints (src/server/public-api, src/server/mcp), and HttpEffect.toWebHandlerWith in the Worker adapter.

• HttpApi was not used, for the same reason as oRPC’s OpenAPI handler: it derives its own OpenAPI document and error encoding, while this contract is a fixed file with hand-specified bodies and headers.
• The router is configured to match paths exactly as published: case-sensitive, no trailing- or duplicate-slash folding. Path parameters may be up to 8 KB long, because user_id has no length limit; the router’s default of 100 characters would reject valid ids.
• /api/v1/* aliases are registered as separate routes rather than through HttpRouter.prefixed. A prefixed route gets a copied request, and the 1 MiB check has already read (and cached) the body on the original one.
• Cost: about 200 kB more Worker bundle (about 50 kB gzipped). The module lives in Effect’s unstable namespace, so its API can change between Effect 4 releases. The 02-public-api scenario pins the wire behaviour (the routing contract test) to catch that.

Linting

Ultracite (Oxlint + oxfmt) with the React and TanStack presets. oxlint-plugin-effect’s recommended preset applies to src/server/**, with two deliberate relaxations:

• effect/noNullish: D1 rows, Better Auth and JSON APIs are nullable.
• effect/noTernary: a style preference.

Platform adapters (src/server/platform/**) may use globals, async functions and Promises, as the plugin’s README recommends. Better Auth’s option file and its plugins (auth-options.ts, dev-sign-in.ts) may use as const and throw APIError, because Better Auth infers its API types from literal tuples and rejects requests by throwing. Four core rules that misread Effect idioms are off for src/**; each is commented in oxlint.config.ts.

Docs site

docs is the documentation: the customer guides, this self-hosting section, the changelog, and an API reference generated from openapi/openapi.json. Blume builds it into static files with Astro. It is a separate build, rather than part of the Vite build, because Blume owns its own Astro pipeline. It lives in its own workspace package so its dependency tree (Astro, sharp, pagefind) stays out of the Worker’s.

• pnpm build runs vite build, the marketing prerender, blume build, then scripts/bundle-docs.ts, which copies docs/dist to dist/client/www/docs. Nothing new is deployed: the same Worker serves the files.
• Blume builds with deployment.base: "/docs", so every link, script and stylesheet already carries the prefix. The Worker maps /docs/x to /www/docs/x/index.html like any other site page. Unknown docs pages get the docs 404, and .md/.txt files are served with charset=utf-8.
• Redirects in blume.config.ts ship as meta-refresh pages. Blume’s host files (_headers, _redirects, vercel.json) aren’t copied.
• The marketing robots.txt lists the docs sitemap, because crawlers only read /robots.txt at the root.
• docs.<domain> (EMITKIT_DOCS_HOST), where the previous Mintlify docs lived, is attached to the Worker and 301s to <site>/docs/<same path>. Mintlify-era paths that moved (/api-reference/*, /self-hosting/*, /concepts/webhooks) have redirects in blume.config.ts.
• pnpm docs:dev runs Blume’s dev server for writing; pnpm dev doesn’t serve /docs.
• pnpm typecheck runs blume validate --strict, which checks links and frontmatter. It doesn’t run blume check, because Blume 1.7.3’s generated navigation code fails its own type check.

Why these resources