| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685 |
- {
- "schemaVersion": "0.1.1",
- "kind": "graph",
- "generatedAt": "2026-08-19T18:24:00.000Z",
- "title": "Batch broadcast sending through Postmark",
- "summary": "Broadcast delivery moves from one Postmark request per recipient to batched requests of 500, with suppression filtering pulled in front of the send and the payload builder extracted into a shared library.",
- "lenses": [
- "architecture",
- "data-flow"
- ],
- "provenance": {
- "repo": {
- "owner": "ohansemmanuel",
- "name": "bestregards",
- "host": "github.com"
- },
- "base": {
- "sha": "3f5c1ab9d24e7f08c6b1a5d3e9074c2b8a6f1d40",
- "ref": "main"
- },
- "head": {
- "sha": "b71e0d4c8a92f5361de7c0b4a8f2593d6c1e8a77",
- "ref": "batch-broadcast-send"
- },
- "pullRequest": {
- "number": 128,
- "title": "Send broadcasts in batches of 500",
- "url": "https://github.com/ohansemmanuel/bestregards/pull/128"
- },
- "generator": {
- "name": "pr-lens-examples",
- "version": "0.1.0"
- }
- },
- "lanes": [
- {
- "id": "web",
- "label": "Next.js",
- "subtitle": "Vercel",
- "order": 0
- },
- {
- "id": "functions",
- "label": "Cloud Functions",
- "subtitle": "Firebase",
- "order": 1
- },
- {
- "id": "external",
- "label": "External",
- "subtitle": "Postmark",
- "order": 2
- }
- ],
- "nodes": [
- {
- "id": "broadcast-composer",
- "label": "Broadcast composer",
- "kind": "ui",
- "delta": "unchanged",
- "lane": "web",
- "subtitle": "app/broadcasts/new",
- "summary": "Where an author writes a broadcast and hits send. Untouched by this change.",
- "files": [
- {
- "path": "app/broadcasts/new/page.tsx"
- }
- ],
- "badges": []
- },
- {
- "id": "queue-route",
- "label": "POST /api/broadcasts/queue",
- "kind": "route",
- "delta": "modified",
- "lane": "web",
- "summary": "Writes the queue document. Now stamps the recipient count and batch size the sender will use instead of leaving batching to the worker.",
- "files": [
- {
- "path": "app/api/broadcasts/queue/route.ts",
- "startLine": 24,
- "endLine": 96
- }
- ],
- "badges": [
- "+38 / -12"
- ]
- },
- {
- "id": "broadcast-queue",
- "label": "broadcastQueue",
- "kind": "datastore",
- "delta": "modified",
- "lane": "functions",
- "subtitle": "Firestore collection",
- "summary": "Queue documents gained batchSize and suppressedCount fields, and results are now written back per batch rather than per recipient.",
- "files": [
- {
- "path": "functions/src/broadcast/schema.ts",
- "startLine": 12,
- "endLine": 48
- }
- ],
- "badges": []
- },
- {
- "id": "send-broadcast-bulk",
- "label": "sendBroadcastBulk",
- "kind": "function",
- "delta": "added",
- "lane": "functions",
- "subtitle": "onWrite trigger",
- "summary": "New trigger handler. Fetches suppressions once, builds batched payloads, and posts them to Postmark in chunks of 500.",
- "files": [
- {
- "path": "functions/src/broadcast/sendBroadcastBulk.ts",
- "startLine": 1,
- "endLine": 142
- }
- ],
- "badges": [
- "new"
- ]
- },
- {
- "id": "build-bulk-payload",
- "label": "buildBulkPayload",
- "kind": "function",
- "delta": "added",
- "lane": "functions",
- "summary": "Turns a broadcast and its recipient slice into a Postmark batch request body.",
- "files": [
- {
- "path": "packages/broadcast-lib/src/buildBulkPayload.ts",
- "startLine": 1,
- "endLine": 74
- }
- ],
- "badges": []
- },
- {
- "id": "get-suppressed-emails",
- "label": "getSuppressedEmails",
- "kind": "function",
- "delta": "added",
- "lane": "functions",
- "summary": "Pulls the Postmark suppression dump once per broadcast so suppressed addresses are filtered before any batch is sent.",
- "files": [
- {
- "path": "packages/broadcast-lib/src/getSuppressedEmails.ts",
- "startLine": 1,
- "endLine": 58
- }
- ],
- "badges": []
- },
- {
- "id": "broadcast-lib",
- "label": "broadcast-lib",
- "kind": "package",
- "delta": "added",
- "lane": "functions",
- "subtitle": "packages/broadcast-lib",
- "summary": "New shared package so the queue route and the sender agree on payload shape and batch size.",
- "files": [
- {
- "path": "packages/broadcast-lib/src/index.ts"
- }
- ],
- "badges": [
- "new package"
- ]
- },
- {
- "id": "process-broadcast",
- "label": "processBroadcast",
- "kind": "function",
- "delta": "removed",
- "lane": "functions",
- "subtitle": "onWrite trigger",
- "summary": "The per-recipient loop this change replaces.",
- "files": [
- {
- "path": "functions/src/broadcast/processBroadcast.ts",
- "startLine": 1,
- "endLine": 118,
- "revision": "base"
- }
- ],
- "badges": []
- },
- {
- "id": "send-single-email",
- "label": "sendSingleEmail",
- "kind": "function",
- "delta": "removed",
- "lane": "functions",
- "summary": "One Postmark request per recipient. Gone with the loop that called it.",
- "files": [
- {
- "path": "functions/src/broadcast/sendSingleEmail.ts",
- "startLine": 1,
- "endLine": 46,
- "revision": "base"
- }
- ],
- "badges": []
- },
- {
- "id": "postmark",
- "label": "Postmark",
- "kind": "external",
- "delta": "modified",
- "lane": "external",
- "subtitle": "Email API",
- "summary": "Same provider, different endpoints: the batch endpoint and the suppression dump replace repeated single sends.",
- "files": [],
- "badges": []
- }
- ],
- "edges": [
- {
- "id": "composer-to-queue",
- "from": "broadcast-composer",
- "to": "queue-route",
- "kind": "http",
- "delta": "unchanged",
- "label": "send broadcast",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "queue-to-firestore",
- "from": "queue-route",
- "to": "broadcast-queue",
- "kind": "data",
- "delta": "modified",
- "label": "enqueue job",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "queue-to-lib",
- "from": "queue-route",
- "to": "broadcast-lib",
- "kind": "dependency",
- "delta": "added",
- "label": "batch size",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "firestore-to-bulk",
- "from": "broadcast-queue",
- "to": "send-broadcast-bulk",
- "kind": "event",
- "delta": "added",
- "label": "onWrite",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "firestore-to-process",
- "from": "broadcast-queue",
- "to": "process-broadcast",
- "kind": "event",
- "delta": "removed",
- "label": "onWrite",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "process-to-single",
- "from": "process-broadcast",
- "to": "send-single-email",
- "kind": "call",
- "delta": "removed",
- "label": "per recipient",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "single-to-postmark",
- "from": "send-single-email",
- "to": "postmark",
- "kind": "http",
- "delta": "removed",
- "label": "POST /email · 1 msg/call",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "bulk-to-payload",
- "from": "send-broadcast-bulk",
- "to": "build-bulk-payload",
- "kind": "call",
- "delta": "added",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "bulk-to-suppressions",
- "from": "send-broadcast-bulk",
- "to": "get-suppressed-emails",
- "kind": "call",
- "delta": "added",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "bulk-to-lib",
- "from": "send-broadcast-bulk",
- "to": "broadcast-lib",
- "kind": "dependency",
- "delta": "added",
- "emphasis": "normal",
- "animated": false,
- "files": []
- },
- {
- "id": "suppressions-to-postmark",
- "from": "get-suppressed-emails",
- "to": "postmark",
- "kind": "http",
- "delta": "added",
- "label": "GET suppression dump",
- "emphasis": "normal",
- "animated": true,
- "files": []
- },
- {
- "id": "bulk-to-postmark",
- "from": "send-broadcast-bulk",
- "to": "postmark",
- "kind": "http",
- "delta": "added",
- "label": "500 msgs/call",
- "emphasis": "hero",
- "animated": true,
- "summary": "The change in one edge: a broadcast to 10,000 recipients drops from 10,000 requests to 20.",
- "files": []
- },
- {
- "id": "bulk-to-firestore",
- "from": "send-broadcast-bulk",
- "to": "broadcast-queue",
- "kind": "data",
- "delta": "added",
- "label": "write results",
- "emphasis": "normal",
- "animated": false,
- "files": []
- }
- ],
- "flows": [
- {
- "id": "send-pipeline",
- "title": "Sending a broadcast",
- "summary": "The path a queued broadcast takes now, from enqueue to per-message results.",
- "delta": "modified",
- "participants": [
- {
- "node": "queue-route",
- "label": "queue route"
- },
- {
- "node": "broadcast-queue",
- "label": "Firestore"
- },
- {
- "node": "send-broadcast-bulk",
- "label": "sendBroadcastBulk"
- },
- {
- "node": "postmark",
- "label": "Postmark"
- }
- ],
- "messages": [
- {
- "id": "enqueue",
- "from": "queue-route",
- "to": "broadcast-queue",
- "label": "enqueue broadcast job",
- "kind": "async",
- "delta": "modified",
- "animated": true,
- "files": []
- },
- {
- "id": "trigger",
- "from": "broadcast-queue",
- "to": "send-broadcast-bulk",
- "label": "onWrite trigger",
- "kind": "async",
- "delta": "added",
- "animated": true,
- "files": []
- },
- {
- "id": "suppressions-request",
- "from": "send-broadcast-bulk",
- "to": "postmark",
- "label": "GET suppression dump",
- "kind": "sync",
- "delta": "added",
- "animated": true,
- "files": []
- },
- {
- "id": "suppressions-response",
- "from": "postmark",
- "to": "send-broadcast-bulk",
- "label": "suppressed addresses",
- "kind": "return",
- "delta": "added",
- "animated": true,
- "note": "Fetched once per broadcast, not once per recipient.",
- "files": []
- },
- {
- "id": "batch-post",
- "from": "send-broadcast-bulk",
- "to": "postmark",
- "label": "POST /email/batch · 500 msgs",
- "kind": "sync",
- "delta": "added",
- "animated": true,
- "repeat": 4,
- "note": "One request per 500 recipients; four for this 2,000-recipient broadcast.",
- "files": []
- },
- {
- "id": "batch-results",
- "from": "postmark",
- "to": "send-broadcast-bulk",
- "label": "per-message results",
- "kind": "return",
- "delta": "added",
- "animated": true,
- "files": []
- },
- {
- "id": "write-results",
- "from": "send-broadcast-bulk",
- "to": "broadcast-queue",
- "label": "write results",
- "kind": "async",
- "delta": "added",
- "animated": true,
- "files": []
- }
- ]
- }
- ],
- "stats": {
- "filesChanged": 14,
- "additions": 486,
- "deletions": 212,
- "chips": [
- {
- "label": "Postmark calls",
- "value": "500× fewer",
- "tone": "hero"
- },
- {
- "label": "New",
- "value": "4 units",
- "tone": "added"
- },
- {
- "label": "Retired",
- "value": "2 units",
- "tone": "removed"
- }
- ]
- },
- "views": [
- {
- "id": "overview",
- "title": "Architecture — blast radius",
- "lens": "architecture",
- "summary": "Everything this change touches, across all three lanes.",
- "scope": {
- "kind": "all"
- },
- "defaultOpen": true,
- "children": [
- {
- "id": "new-batch-path",
- "title": "The new batch path",
- "lens": "architecture",
- "summary": "What replaced the per-recipient loop.",
- "scope": {
- "kind": "selection",
- "lanes": [],
- "nodes": [
- "send-broadcast-bulk",
- "build-bulk-payload",
- "get-suppressed-emails",
- "broadcast-lib",
- "postmark"
- ],
- "edges": [
- "bulk-to-payload",
- "bulk-to-suppressions",
- "bulk-to-lib",
- "suppressions-to-postmark",
- "bulk-to-postmark",
- "bulk-to-firestore"
- ],
- "flows": []
- },
- "defaultOpen": false,
- "children": []
- },
- {
- "id": "retired-path",
- "title": "What was retired",
- "lens": "architecture",
- "summary": "The single-send path, kept visible so a reviewer can confirm nothing else called it.",
- "scope": {
- "kind": "selection",
- "lanes": [],
- "nodes": [
- "process-broadcast",
- "send-single-email"
- ],
- "edges": [
- "firestore-to-process",
- "process-to-single",
- "single-to-postmark"
- ],
- "flows": []
- },
- "defaultOpen": false,
- "children": []
- }
- ]
- },
- {
- "id": "send-pipeline-view",
- "title": "Data flow — sending a broadcast",
- "lens": "data-flow",
- "scope": {
- "kind": "selection",
- "lanes": [],
- "nodes": [],
- "edges": [],
- "flows": [
- "send-pipeline"
- ]
- },
- "defaultOpen": false,
- "children": []
- }
- ],
- "walkthrough": {
- "steps": [
- {
- "id": "batches-of-500",
- "heading": "sendBroadcastBulk and buildBulkPayload added",
- "body": "Nothing loops over recipients any more. The sender works on a whole batch at a time.",
- "stage": {
- "kind": "view",
- "view": "overview"
- },
- "focus": {
- "kind": "selection",
- "lanes": [],
- "nodes": [
- "send-broadcast-bulk",
- "build-bulk-payload",
- "postmark"
- ],
- "edges": [],
- "messages": []
- }
- },
- {
- "id": "suppression-first",
- "heading": "getSuppressedEmails added before the send",
- "body": "It pulls the blocked addresses once, before any batch is built.",
- "stage": {
- "kind": "view",
- "view": "new-batch-path"
- },
- "focus": {
- "kind": "selection",
- "lanes": [],
- "nodes": [
- "get-suppressed-emails",
- "postmark"
- ],
- "edges": [],
- "messages": []
- }
- },
- {
- "id": "old-path-goes-dark",
- "heading": "processBroadcast and sendSingleEmail removed",
- "body": "sendBroadcastBulk does their job for whole batches.",
- "stage": {
- "kind": "view",
- "view": "overview"
- },
- "focus": {
- "kind": "selection",
- "lanes": [],
- "nodes": [
- "process-broadcast",
- "send-single-email"
- ],
- "edges": [],
- "messages": []
- }
- },
- {
- "id": "sequence-start-to-finish",
- "heading": "The send sequence gained 6 new steps",
- "body": "The queue write is the only step that was there before, and it now stamps the batch size.",
- "stage": {
- "kind": "flow",
- "flow": "send-pipeline"
- },
- "focus": {
- "kind": "all"
- }
- },
- {
- "id": "four-batch-calls",
- "heading": "Postmark now gets 500 emails per call",
- "body": "One call per batch, and Postmark answers with a result for each message.",
- "stage": {
- "kind": "flow",
- "flow": "send-pipeline"
- },
- "focus": {
- "kind": "selection",
- "lanes": [],
- "nodes": [],
- "edges": [],
- "messages": [
- "batch-post",
- "batch-results"
- ]
- }
- },
- {
- "id": "blast-radius",
- "heading": "4 parts added, 2 removed, across 3 lanes",
- "body": "A 2,000-person broadcast used to make 2,000 calls to Postmark. It now makes 4.",
- "stage": {
- "kind": "view",
- "view": "overview"
- },
- "focus": {
- "kind": "all"
- }
- }
- ]
- },
- "layout": {
- "direction": "right",
- "laneOrder": [
- "web",
- "functions",
- "external"
- ],
- "rank": {
- "queue-route": 0,
- "send-broadcast-bulk": 1,
- "postmark": 2
- }
- }
- }
|