Skip to content

Instantly share code, notes, and snippets.

@gakonst

gakonst/office-visit-detection-spec.md

Created January 25, 2026 19:35
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save gakonst/ebae569e2f1c77644ae6b95d9e01835a to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save gakonst/ebae569e2f1c77644ae6b95d9e01835a to your computer and use it in GitHub Desktop.
Download ZIP
Office Visit Detection System - Spec
Raw
office-visit-detection-spec.md

Office Visit Detection System

Goal: Automatically detect when team members are traveling to Tempo's SF or NY offices and make it easy for people to meet in-person.

Approach: Detect flights on Google Calendar → Send Slack DM with confirmation buttons → Add confirmed visits to shared calendar + announce in channel.

System Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Google Calendar │────▶│   Detection     │────▶│   Slack Bot     │
│ (flight events) │     │   Service       │     │   (DM + buttons)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                              ┌──────────────────────────┤
                              ▼                          ▼
                     ┌─────────────────┐        ┌─────────────────┐
                     │ Shared Calendar │        │ #sf-office post │
                     │ (Office Visits) │        │ #ny-office post │
                     └─────────────────┘        └─────────────────┘

User Flow

  1. User books flight to SF → airline auto-adds to their Google Calendar
  2. Detection service (daily cron) scans calendars for flight events
  3. Parses destination airport → determines target office
  4. Sends Slack DM:

    ✈️ Looks like you're flying to SF on Jan 28-30. Will you be at the Tempo office?

    [Yes, add me] [No, personal trip] [Don't ask again for this trip]

  5. If confirmed:
    • Adds event to shared "SF Office Visits" calendar
    • Posts to #sf-office: "👋 @user will be in the SF office Jan 28-30"

Components

Component Purpose Build Effort
Calendar Scanner Cron job reads team calendars, finds flight events Medium
Flight Parser Extracts destination airport from calendar event Medium (brittle)
Slack Bot Sends DM with interactive buttons, handles responses Medium
Shared Calendar Writer Adds confirmed visits to shared calendar Low
User Mapping Google email ↔ Slack user ID Low
State Store Tracks sent notifications to avoid duplicates Low

API Requirements & Access Status

Google Calendar API

Capability Required Access Status
Read user calendars (org-wide) Yes ❌ NOT CONFIGURED - No OAuth credentials
List events with search/filter Yes ❌ Blocked by above
Create events on shared calendar Yes ❌ Blocked by above

What's needed:

  1. Google Workspace Admin to enable domain-wide delegation, OR
  2. Each user individually grants calendar read access to service account
  3. OAuth credentials configured at ~/.config/gsuite/credentials.json

API Docs: Calendar API Events.list

Slack API

Capability Required Access Status
Send DMs to users Yes ⚠️ PARTIAL - Can send to channels, DM capability unverified
Interactive message buttons Yes ❌ NOT AVAILABLE - Current CLI has no button/interactivity support
Post to channels Yes ✅ Available via slack send
Map email to Slack user ID Yes ✅ Available via slack users

What's needed for interactive buttons:

  1. Slack App with chat:write, im:write, users:read.email scopes
  2. Interactivity enabled with Request URL endpoint
  3. Server to receive button click webhooks

Alternative without buttons: Send DM with instructions to reply "yes" or "no" - parse text responses instead. Less elegant but no webhook infrastructure needed.

GitHub (for code hosting)

Capability Required Access Status
Create/push to repo Yes ✅ Authenticated as gakonst
Create gists Yes ✅ gist scope available

Likely Failure Points & Mitigations

1. Flight Event Detection (HIGH RISK)

Problem: Airlines format calendar events inconsistently:

  • UA 123: SFO → JFK
  • Flight to San Francisco
  • Trip - New York
  • Confirmation: American Airlines

Mitigations:

  • Start with literal airport code matching (SFO, JFK, etc.) - highest confidence
  • Build corpus of real flight events from team to tune parsing
  • Accept lower recall initially; iterate based on missed detections

2. Calendar Permissions (HIGH RISK)

Problem: Need read access to everyone's calendar.

Options:

  • Domain-wide delegation (requires Workspace Admin approval)
  • Individual OAuth consent (each person must authorize once)
  • Calendar sharing (each person shares calendar with service account)

Recommendation: Domain-wide delegation is cleanest but requires admin buy-in. Start with opt-in individual OAuth for pilot users.

3. Airport → Office Mapping (MEDIUM RISK)

Problem: Which airports map to which office?

Office Primary Airports Edge Cases
SF SFO, OAK, SJC Sacramento (SMF)? Monterey?
NY JFK, EWR, LGA Hartford? Philly?

Mitigation: Start conservative (primary airports only). The confirmation step lets users correct if we miss their airport.

4. Timing & Edge Cases (MEDIUM RISK)

Scenario Problem Handling
Red-eye flights Arrives 6am - which day in office? Use arrival date
Multi-leg trips SFO → ORD → JFK Use final destination
One-way flights Flying home, not visiting Ask in confirmation
Already in city Local employee flying out Ignore outbound-only
Round-trip same day Day trip Include single day

5. Notification Fatigue (MEDIUM RISK)

Problem: Frequent travelers get spammed; personal trips trigger unwanted DMs.

Mitigations:

  • "Don't ask again for this trip" button
  • Store declined trip IDs, don't re-notify
  • Weekly digest option instead of per-flight

Phased Implementation

Phase 0: Manual Baseline (0.5 days)

Create shared Google Calendars "SF Office Visits" and "NY Office Visits". Ask team to manually add events when visiting. Measure adoption after 2 weeks.

Phase 1: Slash Command (1 day)

Build /visiting sf jan 28-30 Slack command that:

  • Adds event to shared calendar
  • Posts to #sf-office / #ny-office

Value: Removes friction of finding/opening calendar. Tests if people will use the system at all.

Phase 2: Flight Detection + Text DM (3-4 days)

  • Daily cron scans calendars (start with opt-in pilot users)
  • Detect flights via airport code regex
  • Send plain-text Slack DM asking for "yes/no" reply
  • Parse replies, add to calendar

Requires: Google Calendar API access for pilot users

Phase 3: Interactive Buttons (2-3 days, if needed)

  • Replace text replies with button interactions
  • Requires webhook endpoint for Slack interactivity

Open Questions

  1. Who is the Google Workspace Admin that can enable domain-wide delegation or approve OAuth scopes?

  2. Shared calendar ownership - Should this be a team calendar or resource calendar?

  3. Channel preferences - Are #sf-office and #ny-office the right channels, or should we create dedicated #office-visits?

  4. Pilot users - Who are 3-5 frequent travelers willing to test with their calendars?

Next Steps

  1. ✅ Spec complete (this document)
  2. ⏳ Get Google Workspace Admin approval for Calendar API access
  3. ⏳ Create shared calendars for SF/NY office visits
  4. ⏳ Build Phase 1 slash command as MVP
  5. ⏳ Recruit pilot users for Phase 2 testing
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment