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.
| Route | Auth |
|---|---|
/webhooks/slack, /webhooks/slack/interactions, /slack/audit | Slack request signature |
/webhooks/linear | Linear webhook secret |
/api/*, /slack/* endpoints | X-API-Key |
/healthcheck | None |
Classify β Gather β Analyzeβ
Every @mention follows the same three steps:
- Classify. A model picks a type and search terms.
- Gather. One place fetches only the data that type needs.
- Analyze. A model answers from the gathered data and the reply is formatted for Slack.
| Type | Data |
|---|---|
| Bug, outage | Code, recent releases, vendor status pages, similar Linear issues |
| Feature | Code, recent releases |
| Question | Code |
| Product | Shopify, Airtable (launches and attributes), BigQuery (restocks and on-order) |
| Discount code | Shopify discounts |
| Documentation | Guru, for CX SOPs |
| Unknown | Suggested 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:
| Setting | Effect |
|---|---|
| Allowed types | The classifier can only pick these. The CX workspace allows product, discount code and documentation |
| DMs enabled | Whether 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β
| Job | When (Pacific) | Channel |
|---|---|---|
| Icebreaker | Monday 9:00 | #olt |
| PR review digest | Weekdays 9:00 | #site-prs |
| Fantasy football leaderboard | Monday 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.