Add meeting finder tool integration

[BillChirico]

📍 Add Meeting Finder Tool Integration

Overview

Enable Sobers Buddy to find and suggest nearby recovery meetings as a supportive action.

---

Goals

• Find meetings near user's location
• Support multiple meeting types (AA, NA, SMART, etc.)
• Show meeting details (time, location, type)
• One-tap directions or call
• Respect privacy (location only when requested)

---

Meeting Types Supported

Type	Description	Data Source
AA	Alcoholics Anonymous	AA.org API
NA	Narcotics Anonymous	NA.org API
SMART	SMART Recovery	SMART Recovery API
Refuge	Refuge Recovery	Refuge Recovery API
Online	Virtual meetings	Various

---

User Flow

1. Trigger: User asks "Find me a meeting" or taps suggestion
2. Permission: Request location access (one-time or always)
3. Search: Query meeting databases within 10-mile radius
4. Display: List of meetings with details
5. Action: Get directions, add to calendar, share

---

Technical Implementation

interface Meeting {
  id: string;
  name: string;
  type: 'AA' | 'NA' | 'SMART' | 'Refuge' | 'Other';
  location: {
    name: string;
    address: string;
    lat: number;
    lng: number;
  };
  schedule: {
    day: string;
    time: string;
    frequency: 'weekly' | 'daily' | 'monthly';
  };
  details: {
    format: 'open' | 'closed' | 'online';
    language: string;
    accessibility: string[];
    notes?: string;
  };
  contact?: {
    phone?: string;
    email?: string;
    website?: string;
  };
}

interface MeetingSearchParams {
  lat: number;
  lng: number;
  radius: number;  // miles
  types?: string[];
  day?: string;
  timeRange?: { start: string; end: string };
}

---

API Integration

Option 1: Meeting Guide API (AA)

• Free, official AA data
• Covers US/Canada
• REST API with location search

Option 2: Custom Aggregation

• Multiple sources (AA, NA, SMART)
• Volvox-managed database
• More comprehensive
• Requires ongoing maintenance

Recommendation: Start with Meeting Guide API, expand to custom

---

UI Components

Meeting List

• Distance from user
• Meeting name and type
• Time and day
• Open/closed indicator
• Accessibility badges

Meeting Detail

• Full address with map
• Directions button (opens Maps)
• Call button (if phone provided)
• Add to calendar
• Share meeting

---

Implementation Tasks

• Research meeting APIs (AA, NA, SMART)
• Design meeting data models
• Build location permission flow
• Implement meeting search API
• Create meeting list UI
• Build meeting detail view
• Add directions integration
• Implement calendar integration
• Cache meeting data locally
• Add "meeting not found" fallback

---

Acceptance Criteria

• Finds meetings within 10 miles
• Supports at least AA and NA
• Shows accurate meeting times
• Directions open in native Maps app
• Works offline with cached data
• Location permission optional (can search by zip)
• Loading state while searching
• Error state for no meetings found

---

Privacy Notes

• Location only used for search, not stored
• User can search by zip code instead
• No meeting attendance tracking
• Optional: Remember preferred meeting types

---

Related

• Parent: [Epic] Sobers Buddy Implementation #412
• Depends on: Set up Vercel AI SDK infrastructure #413 (tool calling)
• Used by: Implement slip/relapse supportive response flow #418 (slip response)

---

Part of Sobers v2