Fitness Studio Member Retention Engine (Fork)

How It Works

1. 1
   Data Extraction

   Connect to Mindbody API using OAuth credentials, pull attendance data for all active members from the past 30 days including class bookings, check-ins, no-shows, and cancellations

   Mindbody Staff API
2. 2
   Member Enrichment

   Retrieve member profile data including join date, membership type, class preferences, and historical booking patterns to build comprehensive member profiles

   Mindbody Client API
3. 3
   Risk Analysis

   Send structured member data to Claude API with risk scoring prompt, analyzing attendance decline patterns, booking frequency changes, and engagement trend deviations

   Claude API
4. 4
   Threshold Processing

   Filter Claude's risk scores against configurable thresholds, categorizing members into low/medium/high risk segments and preparing at-risk member lists

   Custom scoring logic
5. 5
   Alert Generation

   Store high-risk members in database queue and trigger Win-Back Campaigner for immediate outreach, while logging all risk scores for trend analysis

   Database queue system

Implementation

# Churn Risk Scanner Implementation

## File Structure
```
churn_scanner/
├── main.py
├── mindbody_client.py
├── claude_analyzer.py
├── risk_processor.py
├── config/
│   ├── settings.yaml
│   └── risk_prompts.txt
└── data/
    ├── member_queue.db
    └── logs/
```

## Environment Variables
```bash
MINDBODY_API_KEY=your_api_key
MINDBODY_SITE_ID=your_site_id
CLAUDE_API_KEY=your_claude_key
DATABASE_URL=sqlite:///data/member_queue.db
RISK_THRESHOLD_HIGH=0.75
RISK_THRESHOLD_MEDIUM=0.5
LOG_LEVEL=INFO
```

## Key Functions

### main.py
```python
def run_churn_analysis():
    # Load configuration
    config = load_config('config/settings.yaml')
    
    # Initialize clients
    mindbody = MindbodyClient()
    claude = ClaudeAnalyzer()
    
    # Extract member data
    members = mindbody.get_active_members(days=30)
    attendance = mindbody.get_attendance_data(days=30)
    
    # Process each member
    for member in members:
        member_data = enrich_member_profile(member, attendance)
        risk_score = claude.analyze_risk(member_data)
        
        if risk_score > config['risk_threshold_high']:
            queue_for_campaign(member, risk_score)
            
    # Generate weekly report
    generate_summary_report()
```

## Cron Setup
```bash
# Add to crontab (crontab -e)
0 7 * * 1 cd /path/to/churn_scanner && python main.py >> logs/scanner.log 2>&1
```

## Database Schema
```sql
CREATE TABLE at_risk_members (
    id INTEGER PRIMARY KEY,
    member_id TEXT,
    risk_score REAL,
    flagged_date TIMESTAMP,
    status TEXT DEFAULT 'queued'
);
```

Data Flow

Prerequisites

• -Mindbody Staff API credentials with read access to member and attendance data
• -Claude API key with sufficient monthly token limits
• -Python 3.8+ environment with requests, sqlite3, pandas libraries
• -Cron job access on deployment server

Error Handling