Skip to main content

Architecture

One Express service on Cloud Run. It keeps per-workspace settings and a query cache in Firestore and has no other database.

Request flow​

Webhooks answer 200 straight away and do the work in the background, since Slack retries anything slower than three seconds. Repeat Slack events are dropped.

RouteAuth
/webhooks/slack, /webhooks/slack/interactions, /slack/auditSlack request signature
/webhooks/linearLinear webhook secret
/api/*, /slack/* endpointsX-API-Key
/healthcheckNone

Classify β†’ Gather β†’ Analyze​

Every @mention follows the same three steps:

  1. Classify. A model picks a type and search terms.
  2. Gather. One place fetches only the data that type needs.
  3. Analyze. A model answers from the gathered data and the reply is formatted for Slack.
TypeData
Bug, outageCode, recent releases, vendor status pages, similar Linear issues
FeatureCode, recent releases
QuestionCode
ProductShopify, Airtable (launches and attributes), BigQuery (restocks and on-order)
Discount codeShopify discounts
DocumentationGuru, for CX SOPs
UnknownSuggested rephrasings, or a help menu

Code search covers hydrogen-storefront in production.

Workspaces​

Birdy Bot is installed in two Slack workspaces. Each workspace's settings live in Firestore:

SettingEffect
Allowed typesThe classifier can only pick these. The CX workspace allows product, discount code and documentation
DMs enabledWhether DMs get customer and order lookups. Only the CX workspace has DMs on

Threads​

A follow-up in a thread reuses the type of the first message the bot answered and skips classification. A clarification (a help menu or suggested rephrasings) doesn't set the thread's type, so a rephrased reply is classified fresh. The thread cache is in memory, so it resets on each new instance and every hour.

Answers are cached in Firestore by meaning for 4 hours, so a near-identical question returns the stored answer.

Replacements​

replace <order> in a DM finds the order in Shopify, asks cartographer-api for a recommendation per dress, and searches catalog-api for other styles that would arrive in time. The reply has a picker per dress and a button that creates a 100% discounted replacement draft order in Shopify.

Scheduled posts​

JobWhen (Pacific)Channel
IcebreakerMonday 9:00#olt
PR review digestWeekdays 9:00#site-prs
Fantasy football leaderboardMonday 9:00, with a Tuesday 10:00 correction#premier-league

Cloud Scheduler calls the endpoint and the post happens in the background. The icebreaker remembers past questions in Firestore so it doesn't repeat them.