# 05 — ShowingTime Replacement

## Context
Fogbreak replaces ShowingTime for all showing management. ShowingTime handles 90% of in-person home tours in the US. We build this natively with AI enhancements ShowingTime doesn't have.

## Full Feature Set to Build

### 1. Showing Scheduling Engine
Create `app/api/showings.php`:
- 24/7 appointment scheduling via web, mobile, and API
- Request → confirm → complete → feedback lifecycle
- Multiple confirmation methods: auto-confirm, manual, SMS reply (Y/N), email
- Configurable minimum notice (2hr, 4hr, 24hr per listing)
- Configurable max daily showings per listing
- Blackout times (seller dinner hours, holidays)
- Double-booking prevention
- Lockbox/access instructions (revealed only after confirmation)
- Duration settings per listing (30min, 45min, 1hr)

### 2. Multi-Showing Cart (ShowingCart)
- Agents select multiple listings to show in one trip
- Drag-and-drop reorder
- AI route optimization (minimize drive time between showings)
- Total estimated time calculation
- One-click request all showings in cart
- Calendar integration (block time for showing tour)

### 3. Route Optimization (SmartRoute)
- Given N listings, calculate optimal visit order
- Use Google Maps Directions API or OSRM for drive times
- Factor in showing time windows (if listing has restricted hours)
- Provide turn-by-turn directions between showings
- Offline mode: cache route for areas with poor connectivity

### 4. Feedback Collection
- Auto-send feedback request after showing completes
- Customizable feedback form per listing (overall rating, price opinion, buyer interest, free text)
- Up to 9 follow-up requests if no response (configurable interval, max 5 days between)
- Agent headshot and listing photo in feedback form
- Anonymous feedback option
- Aggregate feedback dashboard for listing agent

### 5. Listing Agent Dashboard
- Real-time showing activity per listing
- Weekly activity charts and statistics
- Feedback summary with ratings distribution
- Days since last showing
- Showing-to-offer conversion tracking
- Comparative activity (your listing vs market average)

### 6. Seller Portal (Home by ShowingTime replacement)
Create or extend `app/portal.html`:
- Seller sees all upcoming and past showings
- Real-time notifications when showing is requested/confirmed/completed
- Feedback from buyer's agents (filtered for seller-appropriate content)
- Activity charts and statistics
- Market comparison data
- No login required if using magic link

### 7. Broker/Office Management
- Office-wide showing dashboard
- Agent performance: showings conducted, feedback response rate, conversion
- Multi-office support (filter by office)
- Part-time appointment center mode (forward to answering service after hours)
- Bulk listing preference management

### 8. MLS Integration
- "Schedule a Showing" button injected into MLS listings
- Sync listing data from MLS feed
- Auto-create showing preferences when new listing enters MLS
- RESO Web API compliance for data exchange

### 9. Notifications
- Push notifications (via mobile app) for new requests, confirmations, cancellations
- Email notifications with one-click confirm/decline
- SMS notifications with Y/N reply to confirm
- Configurable notification preferences per agent
- Seller notifications (showing requested, completed, feedback received)

### 10. AI Enhancements (ShowingTime doesn't have these)
- AI suggests optimal showing times based on listing activity patterns
- AI generates personalized showing confirmation messages
- AI flags feedback patterns (e.g., "3 consecutive 'price too high' → suggest price reduction")
- AI predicts showing-to-offer probability based on feedback signals
- AI auto-generates seller report summaries

## Database Tables
Use the tables from `02-DATABASE-REDESIGN.md`:
- `showings`, `showing_feedback`, `showing_routes`, `showing_preferences`

## API Endpoints for showings.php
```
GET  /api/showings.php?action=list                    # List showings (filterable)
GET  /api/showings.php?action=detail&id=X             # Showing detail
POST /api/showings.php?action=request                  # Request a showing
POST /api/showings.php?action=confirm&id=X             # Confirm
POST /api/showings.php?action=decline&id=X             # Decline
POST /api/showings.php?action=cancel&id=X              # Cancel
POST /api/showings.php?action=complete&id=X            # Mark complete
POST /api/showings.php?action=submit_feedback          # Submit feedback
GET  /api/showings.php?action=feedback&showing_id=X    # Get feedback
POST /api/showings.php?action=optimize_route           # AI route optimization
GET  /api/showings.php?action=listing_activity&prop=X  # Activity stats
GET  /api/showings.php?action=agent_performance        # Agent stats
POST /api/showings.php?action=set_preferences          # Listing preferences
GET  /api/showings.php?action=seller_dashboard&prop=X  # Seller view
```

## Cron Jobs (add to cron.php)
- `showing_reminders`: 1 hour before showing, remind buyer agent + seller
- `feedback_requests`: After completed showing, send feedback request
- `feedback_followup`: Re-send feedback request if no response (up to 9x)
- `showing_analytics`: Calculate daily showing stats per listing

## Acceptance Criteria
- [ ] Full showing lifecycle: request → confirm → complete → feedback
- [ ] Multi-showing cart with drag-and-drop
- [ ] AI route optimization between showings
- [ ] Automated feedback collection with configurable follow-ups
- [ ] Listing agent dashboard with activity charts
- [ ] Seller portal with real-time showing visibility
- [ ] Broker/office management dashboard
- [ ] Push/email/SMS notifications at every stage
- [ ] AI enhancements: optimal times, feedback patterns, price reduction alerts
- [ ] All features tenant-aware and market-aware