Bravocado 🥑

The tastiest way to build a culture of gratitude in your Slack workspace.

한국어

Introduction

Bravocado is a gamified peer-to-peer recognition bot for Slack. We believe feedback shouldn't be boring forms—it should be fun!

When a teammate helps you out, simply send them an avocado emoji. Bravocado tracks these interactions, manages daily allowances, and helps team members grow from a tiny "Seed" to "Holy Guacamole" status.

Key Features

1. 🥑 Avocado Giving

• Simple Syntax: Mention teammates and add 🥑 (or :avocado:) to your message.
• Multi-User Support: @Alice @Bob 🥑 sends 1 avocado to each person.
• Multi-Avocado Support: @Alice 🥑🥑 sends 2 avocados at once.
• Reaction Support: Add :avocado: reaction to any message to send 1 avocado.
  • React to someone else's message → sends to the message author.
  • React to your own message with mentions → sends to the mentioned users.
• Smart Notifications: Recipients get a DM with the sender's name, channel, and original message.

2. ⚖️ Fair Distribution (All-or-Nothing)

To ensure fairness, Bravocado uses all-or-nothing logic:

• If you try @Alice @Bob @Charlie 🥑 but only have 2 avocados left, the transaction is cancelled.
• This prevents scenarios where only the first few people receive rewards while others don't.
• You'll receive an ephemeral error message visible only to you.

3. 🧺 Daily Limits

• Every user receives 5 avocados daily to give away.
• Balances reset at midnight KST.
• Self-Gifting Prevention: You cannot give avocados to yourself—they're for sharing!

4. 🏠 Home Tab Dashboard

Click on the Bravocado app in Slack to view your App Home:

• My Stats: Total received, total given, and remaining daily balance.
• Top Givers: Leaderboard of the most generous teammates.
• Top Receivers: Leaderboard of the most recognized teammates.

5. 🏆 Progression System (Titles)

Users earn titles based on their activity:

Count	Giver Title	Receiver Title
500+	Master Farmer 👨‍🌾	Holy Guacamole 👑
250+	Harvest Machine 🚜	Certified Fresh ✨
100+	Tree Hugger 🌳	Big Avo Energy 🌳
50+	Green Thumb 🪴	Warming Up ☀️
10+	First Rain 🌧️	Just Watered 💧
0–9	Dirt Digger ⛏️	Seed Mode 🌱

6. 📊 Weekly Reports

Every Monday at 09:00 KST, each user receives a DM summarizing the past week:

• Top 5 global givers and receivers
• Your personal top 5 recipients

7. 🎭 Avocado Jokes

Mention Bravocado with a trigger phrase to get a random avocado joke:

• Korean triggers: @Bravocado 잘 익었니? or @Bravocado 농담
• English triggers: @Bravocado make it ripe or @Bravocado tell a joke

---

Tech Stack

• Runtime: Node.js (Vercel Serverless Functions)
• Framework: @slack/bolt v4
• Database: Supabase (PostgreSQL + RPC)
• Deployment: Vercel

---

Getting Started

1. Database Setup (Supabase)

Run supabase/schema.sql in your Supabase SQL Editor. It creates:

• profiles — Per-user give/receive counts and daily balance
• transactions — Logs every avocado transfer with context
• give_avocado() — Transactional RPC for atomic transfers
• reset_daily_avocados() — Scheduled function to reset balances at midnight KST

2. Environment Variables

Configure the following in your .env file or Vercel Dashboard:

# Slack API
SLACK_BOT_TOKEN=xoxb-your-token
SLACK_SIGNING_SECRET=your-signing-secret

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key

# Cron Authentication
CRON_SECRET=your-cron-secret

3. Slack App Configuration

Bot Token Scopes:

• app_mentions:read — Detect @Bravocado mentions for joke requests
• channels:history — Read message content for reaction handling
• chat:write — Post messages and ephemeral messages
• reactions:read — Detect avocado emoji reactions
• users:read — Fetch user display names

Event Subscriptions:

• message.channels — Detect avocado messages
• reaction_added — Detect avocado reactions
• app_home_opened — Render the Home tab dashboard
• app_mention — Respond to joke requests when mentioned

4. Deploy to Vercel

1. Link the repo to a Vercel project.
2. Add environment variables in the Vercel dashboard.
3. Deploy — vercel.json handles routing and cron scheduling automatically.

The cron job (0 0 * * 1) triggers /api/weekly-report every Monday at 00:00 UTC.

5. Testing Weekly Report

You can manually trigger the weekly report endpoint for testing:

curl -X POST https://your-app.vercel.app/api/weekly-report \
  -H "Authorization: Bearer your-cron-secret"

Replace your-cron-secret with your actual CRON_SECRET environment variable value.