Bunker Bot Reference

Three services and two model providers, none of them a machine anybody has to keep running.

flowchart LR
  U["members
in Discord"] -->|"slash command
button, select, form"| D["Discord
application"]
  D -->|signed POST| W["Cloudflare Worker
bunker-bot"]
  W -->|REST| N["Notion
11 databases"]
  W --> KV["KV
caches"]
  W --> R2["R2
photos · audio
transcripts"]
  W -->|"speech to text"| G["Groq
Whisper"]
  W -->|"minutes, tasks"| M["Gemini"]
  CRON["cron */10"] --> W
  W -->|"embeds, DMs"| D

Discord is the interface. The app runs on HTTP interactions, not a gateway connection — Discord posts each interaction to the Worker and waits for a reply. Every request is Ed25519-signed and verified before it is parsed; an unsigned or badly-signed request gets a 401 and is never processed.

The Worker is all the logic. One file, no npm dependencies, pasteable into the Cloudflare dashboard. It holds no state of its own beyond its caches and object stores.

Notion is the database and the human interface to the data. Anything the bot writes is visible and editable by a person, and anything a person edits is picked up within ten minutes.

The model providers are optional and separable. Groq transcribes; Gemini writes the minutes and extracts the tasks. Either can be swapped for Workers AI, and with neither key set every other part of the bot carries on untouched — only /notes refuses, and it says why.

Three invariants hold the whole thing up. Breaking any of them corrupts counts silently, which is the worst way for an inventory system to fail.

The ledger is append-only

Counts are never stored. On Hand is derived: Qty Stocked plus every ledger row's effect. To change a count you add a row; you never edit a number. This is immune to lost updates, keeps rows at zero instead of deleting them, and gives a complete audit trail for free.

Every item carries three numbers

Allocation deliberately does not change On Hand. The club still owns the gearhead; it just belongs to ARCTOS now.

The approval gate is arithmetic, not policy

A ledger row with Status of Pending or Denied contributes zero to every count. The gate is therefore real rather than advisory — a pending request cannot move stock even if someone forgets to look at it. Approving it in Notion or in Discord does the same thing.

Formulas are duplicated, by necessity

The Notion API never returns formula or rollup values — only an opaque reference. The Worker therefore recomputes On Hand, Reserved and Available itself, mirroring the Notion formulas exactly, including the two rules above.

This means the Notion formula and the Worker code must be changed together, by hand, forever. It is the single most likely source of a future bug. If counts in Discord ever disagree with counts in Notion, this is why.

Serials are one fixed shape

BURC-0001 through BURC-9999, then BURC-10000 — padded to a minimum of four digits, never truncated. Notion's own column shows the raw number; the bot is what people read and print, and it shows this. Every lookup normalises first, so 123, burc-123, a scanned barcode and an old unpadded label all resolve to the same item, and BURC-123 can never be mistaken for BURC-1230.

Proposals are not assignments

Anything the bot infers — a task lifted from a transcript, an owner guessed from context, a supplier parsed out of a part number — lands in a state that is visibly incomplete and waits for a person. Tasks arrive as Proposed with nobody on them; the supplier backfill leaves a field empty rather than writing a guess. A guess written into a structured field looks like a fact forever afterwards, and somebody acts on it eighteen months later with nothing in the record to say it was ever uncertain.

Eleven data sources. The IDs are what the Worker's variables point at.

Columns the bot owns

Edit these by hand and they will be overwritten:

• Members → Name — the live Discord server nickname, refreshed on every check-in and every nudge. Put durable notes about a person in Notes.
• Members → Last Seen, Status, Nudges Sent, Last Nudged — retention state.
• Inventory → Flag, Flag Note — set by /report, cleared by the resolve button.
• Checkout Log → Decided By — this is also what stops an approval being announced twice.
• Tasks → Block Msg — channelId|messageId of the card announcing a block, so clearing it can strike that card through. Meaningless to a human and safe to ignore.
• Tasks → Nudges, Last Nudged, Blocked Since — chase state.

Columns the bot fills but never overwrites

The supplier backfill writes Supplier, Supplier PN and MPN on inventory rows only where they are empty. Anything a person has typed is left alone permanently, so the backfill is safe to re-run after hand-fixing rows.

/health is the first thing to open when anything is wrong. Every route is wrapped in a try/catch that returns readable JSON — an uncaught throw here would surface as an opaque Cloudflare 1101 with nothing to debug.

Thirty-seven, guild-scoped. Every reply is ephemeral — only the person who ran it sees it. Transactions are announced separately in the log channel, so testing never spams the server.

Finding things

Stock movement

Projects

Work

Buying

Meetings and attendance

Every control encodes its whole meaning in a custom_id of at most 100 characters. Nothing is stored server-side, so pagination costs zero writes and a button pressed three days later still works.

Why the DM buttons exist

A DM is a push, so the push carries the action. Tapping Done in a DM beats going back to the server to type /done, and buttons work in DMs with no extra machinery.

Slash commands do not. Guild-scoped commands can never appear in a DM at any price — that is a Discord rule, not a configuration. /register?scope=global exists and does publish commands that work in DMs, but global commands take minutes to an hour to propagate and the three that pick a member or post to a channel still cannot work there. Buttons were the better answer; the global path is left in for anyone who wants to revisit it.

A DM interaction also carries user but no member, so every role check would silently fail. The Worker looks the person up in the guild once per interaction and synthesises the member object, and if they have left the server it says so rather than quietly granting nothing.

The longest-running thing the bot does, and the only one that cannot fit inside a Discord interaction.

flowchart TD
  A["/notes with a recording"] --> B["parked in R2
pending/id"]
  B --> C["cron picks it up
15-minute budget"]
  C --> D["Groq Whisper
transcript"]
  D --> E["Gemini
minutes"]
  D --> F["Gemini
task extraction"]
  E --> G["Notion meeting page
summary, decisions, transcript"]
  F --> H["assignment cards
nobody assigned yet"]
  D --> I["kept in R2
text/meetingId"]
  I -.->|"/retask"| F
  C --> J["audio deleted"]

Why the cron and not the command

ctx.waitUntil() is capped at 30 seconds after the reply is sent, and a Worker killed at that cap reports nothing at all — which looks exactly like the bot stalling mid-sentence. Transcribing an hour of audio does not fit in 30 seconds. Cron triggers get fifteen minutes, so the command parks the file and returns immediately, and the next scheduled pass does the work. Expect minutes within about ten minutes of handing in the recording.

A job that keeps failing is retried for 45 minutes, then moved to failed/ so it stops consuming a slot every ten minutes, and the failure is reported with the error attached.

What gets kept, and what does not

The audio is deleted the moment the transcript exists. The transcript is written to the Notion page inside a collapsed toggle, and a copy is kept in R2 under text/ so /retask can re-read it later. That copy is the same words already on the Notion page — it is somewhere the Worker can read cheaply, not a second disclosure. Transcripts are a few kB each; a decade of weekly meetings is under a megabyte.

Which model does what, and why

Groq's free tier allows 6,000 tokens per minute including input. A 90-minute transcript is roughly 16,000 tokens, so it cannot be summarised in one call there at all — it forces small chunks and worse minutes. Gemini allows a million. That is the whole reason two providers are wired in rather than one.

Model failures are two different problems

Size limits

The cap is 24 MB, just under Groq's free-tier file limit. A 90-minute meeting recorded as compressed audio is about 20 MB and fits; on iPhone that is Settings → Voice Memos → Audio Quality → Compressed. Video is accepted as a container but is 10–50× larger for the same speech, so in practice only short clips fit. A url: option takes a direct link for files too big to attach to Discord.

Two ways in: assigned directly with /task, or extracted from a meeting. The extracted ones are the interesting half.

Extraction asks what work the meeting created

This is a dedicated pass over the raw transcript, not a scrape of the minutes. The distinction is the whole point, and it was learned the hard way.

The minutes have an Action items section, and reading it seems obviously right. But that section answers a different question — what did somebody say out loud that they would do — and in a real club meeting the answer is almost nothing. People decide to show a video on a TV; nobody ever says "I will edit the video." The work is implied by the decision. Scraping stated commitments misses all of it while faithfully capturing whichever passing remark happened to have a name next to it.

So the extractor is told plainly: for every decision, ask what somebody has to physically buy, build, book, write, bring, fix or ask before that decision is true. It returns structured data, and each proposal carries:

Expect this to produce more cards than a scrape would, some of them noise. That is the intended trade: Not a task kills a bad one in a single tap, and a task nobody proposed is invisible forever.

Nothing is auto-assigned, ever

A transcript has no speaker labels, so any owner the model names is an inference from context rather than a fact. Auto-assigning on an inference nags people for work they never agreed to, which is exactly how a task system loses everyone's trust. Every extracted task is filed as Proposed with nobody on it, and a card goes to the assignment channel:

📋 TSK-9
Source a TV for the demo table
Project: ARC · ARCTOS

Nobody volunteered for this — it follows from showing video instead of the robot.
No owner was named.

[ Assign to…            ▾ ]
[ Project: ARC · ARCTOS ▾ ]
[ Set a due date ]  [ Not a task ]

The guess, where there is one, is shown and never applied. The project select stays usable after assigning — filing and assigning are separate decisions, and a control that vanishes after one use is worse than one that stays.

Blocking transfers the chasing

/block takes who you are waiting on and what you need from them. The task moves to Blocked, the blocker is DMed with an Unblock button, and the daily chase switches from the owner to the blocker — the person who can actually move it. Clearing it tells the original owner they can carry on and restarts their clock at zero.

The card announcing a block is edited in place when it clears, rather than left lying or deleted, so the record of how long the block lasted survives. That is what Block Msg on the Tasks database is for.

Re-running

Filing twice would double every card, so a second /notes on the same meeting files nothing — but it now says so in the minutes embed, because a silent no-op looks identical to extraction finding nothing. /retask is the deliberate redo: it bins the unassigned proposals, keeps anything somebody already owns, and extracts again from the stored transcript.

Turns scattered "can we buy…" messages into one approved list per supplier that somebody pastes and pays for.

flowchart LR
  A["/request"] --> B["Pending"]
  B -->|"lead approves"| C["Approved"]
  B -->|"lead denies"| D["Denied"]
  C -->|"/orders → Mark ordered"| E["Ordered"]
  E -->|"box arrives"| F["Received"]
  F -->|"/restock"| G["on the shelf"]

No cart API is involved, and none is needed

DigiKey, Mouser and Amazon Business all accept a pasted part,quantity list in their bulk-order box. That cannot break when a vendor redesigns their site, needs no API key, and works identically for suppliers with no API at all. /orders produces exactly that, grouped by supplier:

📦 Ready to order — 3 lines

DigiKey — 2 lines · $14.00
1N4148,50
MAX11206EEE+-ND,2
Paste straight into their bulk order box.

McMaster — 1 line · $20.00
91290A115,100
This supplier has no paste box — order these by hand.

About $34.00 in total

[ Mark DigiKey ordered ]
[ Mark McMaster ordered ]

Suppliers that have no paste box say so rather than pretending. Lines with no recorded price are counted separately instead of silently treated as free.

The supplier backfill

Most inventory part numbers were recorded as prose — sometimes a distributor SKU, sometimes an MPN in brackets, sometimes a note about what could not be confirmed. /backfill splits the unambiguous ones into Supplier, Supplier PN and MPN.

Anything else is left alone: CM3+ (variant to confirm: /Lite, /8GB…), 621772 (motor) / V692821-1.1 (gearhead), Cast marking '402 666 24V'. Those need somebody holding the part, and an empty field is honestly incomplete where a guess is quietly wrong.

Deliberately not built

• Automatic reordering. A bot that spends club money with no person in the loop is a bad idea at any budget.
• Fuzzy matching from descriptions. "12V power supply" matches four hundred parts and picks the wrong one silently. Exact MPN matching is reliable; description matching is not, and its failures are quiet.
• Parametric search in Discord. DigiKey's own site is better at this than any embed. The bot's job is the record, not the browsing.
• Automatic substitutions. "Equivalent" is an engineering judgement.

Labels

A Raspberry Pi in the bunker runs labeld, polls /labels/next every five seconds, renders the label, prints it, and confirms. The Worker never pushes — the Pi has no inbound route and needs none. A job claimed but not confirmed within ten minutes goes back in the queue, so a Pi that loses power mid-label loses nothing. Failures post to the errors channel with the serial.

The label carries the serial three ways for three readers: a QR of PUBLIC_BASE/i/BURC-0123 for phones, Code 128 bars along the bottom for the keyboard-wedge scanner, and the text for people. The renderer adapts to any tape from 12 mm up; bars are dropped under 18 mm where they would be too short to scan. Which printer is behind the Pi is a config line — CUPS, Brother QL, or a captured raw stream for the Epson. The Pi folder's README carries the decision tree.

One cron trigger — */10 * * * * — dispatches everything by checking the clock. Cloudflare allows five triggers on the free plan; this uses one, and adding a job costs nothing.

Why ten minutes and not one

Cloudflare permits * * * * *, and 1,440 firings a day is nothing against 100,000 requests. The wall is KV writes: 1,000 a day on the free plan, and every firing writes both caches.

The fix, if a faster cron is ever wanted: write to KV only when the rebuilt blob actually differs from the cached one. Reads are the cheap resource (100,000 a day), writes the scarce one, so comparing before writing collapses steady-state writes to near zero. The slot checks would need narrowing to minute === n at the same time.

Worth knowing what the cron is actually for, though: stock writes already clear their own cache, so a checkout is reflected on the very next read regardless of cadence. The timer exists to notice edits made in Notion by a person. Ten minutes is a reasonable latency for that, and a faster cron buys very little for what it spends.

Retention rules

A member is DM'd only when every one of these is true. They are conservative on purpose — the failure mode of a retention system is becoming the thing people mute.

• They have attended at least once. The bot never chases somebody who never came.
• They missed both of the last two meetings.
• They have not been nudged in 7 days.
• They have had fewer than 2 nudges, ever.
• No DMs is unticked and their status is not Alumni or Left.
• They are still in the server — checked live; a leaver is marked Left and never messaged.

Attending anything resets the counter to zero. The second nudge carries the exit survey and is the last message that person ever receives from the bot. Nudges address people by their server nickname, not any name they may never have filled in on a Notion row.

Bindings

Required variables

Missing any of these and /health returns a 500 naming them.

Optional variables

Each feature is inert without its own variables and says so rather than failing.

Discord permissions the bot needs

• Send Messages and Embed Links in the log, approvals, errors, nudge, assignments, tasks and minutes channels — and it must be a member of the private ones, or posts vanish silently.
• Manage Events for /event.
• Scopes bot and applications.commands at invite time.

KV

R2

R2 operations through a binding are not subrequests and do not count against the 50-per-invocation ceiling. That is why the minutes pipeline can move whole files around freely while being careful about every Notion write.

The minutes job is the tight one

Every other path uses a handful of subrequests. This one adds up, so it is worth keeping in view:

Other batch limits set by the same ceiling: 15 overdue DMs per sweep, 6 retention DMs per run, 5 new meetings per sync, 20 requests closed per button press, 40 rows per backfill pass, 1 minutes job per cron firing. Anything above the cap rolls to the next firing rather than failing.

The things that will bite whoever inherits this. Most were learned by being bitten.

Platform constraints that cannot be worked around

• The bot cannot see events. No member joins, no messages, no reactions, no voice — those need a gateway connection a Worker cannot hold. Everything starts with a command, a button, or the clock. Where an event is wanted, the pattern is a pinned message with a button. This is also why the bot cannot sit in a voice channel and record a meeting itself — somebody records and hands the file to /notes.
• Three seconds to reply or Discord shows "the application did not respond." Anything slower acknowledges first and edits its own reply.
• ctx.waitUntil() is capped at 30 seconds after the reply, and a Worker killed at that cap reports nothing — indistinguishable from a stall. Long work belongs on the cron.
• Interaction tokens die after 15 minutes. This is why approvals post a new message rather than editing the original request — a decision usually takes longer than that.
• Guild commands can never appear in DMs. Not a setting. See §06.
• A DM interaction has user but no member, so every role check fails unless the member is looked up. The Worker does this automatically.
• Notion file URLs expire in about an hour; Discord CDN links in about a day. Neither can be stored. This is the entire reason R2 exists here.
• Formula and rollup values are unreadable through the Notion API. See §02.
• DMs are opt-out. A member can block server-bot DMs and the send simply fails. Every DM path has a channel-mention fallback.
• Discord limits: 5 buttons per row, 5 rows per message, 25 options per select, 100 characters per custom_id. The project picker slices to 24 plus "No project" for exactly this reason.

The printer is the only thing that is not serverless

A Pi in a cupboard is a machine somebody has to keep alive. It is deliberately as dumb as possible: no state, no inbound connection, restart-on-crash, and a queue that lives on the Worker, so the Pi being off for a week costs nothing but a week of labels waiting. /health shows when it last checked in. If it dies for good, any Linux box with Python and the printer plugged in replaces it in ten minutes.

Discord gives you three names

And only one is the one members recognise:

The trap: when somebody is picked in a command option, the nickname is in resolved.members[id].nick, not resolved.users. Code that only reads resolved.users cannot reach the nickname and falls through to the handle every time — silently, and then writes it into Notion where it stays. Everything now goes through memberName(), actorName() and pickedName(); use those rather than reaching into the interaction by hand.

Verifying a change before deploying

Local maintenance

• TZ_OFFSET is manual. Cloudflare has no timezone awareness. Set it to -5 on 1 November and -4 in March, or every scheduled job drifts an hour.
• Synced meetings default to Kind: General. If socials run as Discord events too, retag them — otherwise skipping two socials reads as lapsing.
• Meeting sync is create-only. Move a Discord event after its Notion row exists and the row keeps the old time. Deliberate: two-way sync would silently overwrite hand edits.
• Due Back is never set by /checkout. The daily overdue sweep therefore has nothing to find until dates are set by hand. Adding a due: option is a small change.
• Task nagging needs both an owner and a due date. A task with one and not the other is never chased. This is the most common reason somebody says "the bot didn't remind me."
• Flags do not block anything. A part marked Broken still checks out. Enforcing it is one line, but a rule nobody maintains just teaches people to route around the bot.
• Old Notion rows keep whatever name was current when they were written. Anything with a Discord ID renders as a live mention and self-corrects; plain stored strings do not.
• /img/ URLs are public to anyone holding them — necessarily, since Discord fetches them to render embeds.

Deploying a change

1. Check the file as a module: cp worker.js /tmp/x.mjs && node --check /tmp/x.mjs
2. Worker → Edit code → select all → paste → Deploy.
3. Added or changed a variable or binding? Deploy again — they do not apply until you do.
4. Added, removed or renamed a command or one of its options? Visit /register?secret=….
5. Added a Notion database? Connect it to the integration, or every call to it 404s.
6. Open /health and read it.

Diagnosing

Undoing things

Delete the ledger row. Counts are derived, so they follow immediately — there is nothing else to unwind. The same is true of attendance rows and bring requests. Never fix a count by editing a number.

Handover

Five things must survive the person who built this:

• The Discord application should be owned by a Team, not a personal account.
• Cloudflare and Notion should be on the club address, not a student one that expires at graduation.
• worker.js belongs in the club GitHub, with this document beside it.
• REGISTER_SECRET, the bot token, and the model API keys need to be somewhere the next president can reach.
• The model API keys are the one recurring cost risk — both are free tiers on personal accounts today. Moving them to club accounts is worth doing before the handover, not during it.

Designed, understood, deliberately not done.

Next, if anything

• Live distributor pricing. Mouser is a plain API key; DigiKey is OAuth2 with roughly ten-minute tokens, so it needs a KV token cache. The payoff is price breaks, stock and lead time on /item, plus a /source picker that confirms a match once and pins it forever — the same confirm-once principle as the assignment board. It reaches perhaps 40% of the catalogue; the industrial parts have no public API and no public price and never will.
• QR check-in. A browser request carries no Discord identity, so a scan only knows who scanned via Discord OAuth identify — one authorise tap, silent thereafter. Would write to the same Attendance table as the button.
• QR redirect through the Worker. Would let every printed label be re-pointed without reprinting. Worth deciding before the next label print run.
• Public catalogue page. Cheap now, since photos already have permanent URLs.
• /join and role self-select. Replaces the join event the bot cannot receive.
• Certification-gated checkout. Turns a safety policy into something the software enforces.

Not code problems

Roughly 30 inventory rows have a part number that is a sentence rather than a number — CM3+ (variant to confirm), 621772 (motor) / V692821-1.1 (gearhead), Cast marking '402 666 24V'. Another 54 have no location. No amount of software fixes these; they need somebody standing at the shelf with the part in their hand.