# ShiftOps Team Estimation - Summary


**Last Updated:** 2025-11-20

High-level overview of team size estimation approach, key principles, constraints, and links to detailed documentation.

## Overview

ShiftOps uses a multi-factor weighted approach to estimate team size for businesses based on Google Places API data. The estimation considers customer volume, operating hours, service complexity, quality indicators, and review velocity.

## Key Principles

1. **Consistency:** Same formula across all implementations (PHP backend, PHP API, JavaScript report, JavaScript loading)
2. **Realism:** Industry-specific caps prevent unrealistic estimates (restaurants max at 25 employees)
3. **Multi-factor:** Multiple factors contribute to estimate (not just review count)
4. **Validation:** Bounds and safety checks ensure realistic values
5. **Transparency:** Detailed factor breakdown and confidence scoring

## Current Implementation Status

✅ **All implementations updated and consistent**

- PHP Backend (`shiftops-cost-calculator.php`): Line 110
- PHP API (`shiftops.php`): Line 2047
- JavaScript Report (`shiftops-report.php`): Line 7288
- JavaScript Loading (`shiftops.php`): Line 1949

## Validation Bounds

**Restaurant:** Min 5, Max 25 (capped at 25)
**Cafe:** Min 3, Max 15 (capped at 15)
**Bar:** Min 3, Max 25 (capped at 25)
**Store:** Min 2, Max 30 (capped at 30)
**Hospital:** Min 8, Max 60 (capped at 60)
**Pharmacy:** Min 3, Max 20 (capped at 20)
**General:** Min 3, Max 30 (capped at 30)

## Volume Factor Caps

- **Restaurants with 2000+ reviews:** 4.0x cap (reduced from 6.0x to prevent unrealistic inflation)
- **Other businesses:** 6.0x cap
- **All businesses:** Minimum 0.3x

## Safety Checks

- **Restaurant cap:** Additional validation after location multipliers ensures restaurants never exceed 25 employees
- **Applied in all implementations:** Prevents location multipliers from inflating values unrealistically

## Data Consistency

**Loading screen and report page use same priority order:**

1. `cost_savings.team_size_estimate` (from API)
2. `online_presence.team_size_estimate` (from API)
3. Fallback calculation (same function with same parameters)

**This ensures consistent values between loading screen and report page.**

## Factor Weights

| Factor             | Weight |
| ------------------ | ------ |
| Customer Volume    | 35%    |
| Operating Hours    | 25%    |
| Service Complexity | 20%    |
| Quality/Scale      | 15%    |
| Review Velocity    | 5%     |

## Recent Changes (January 2025)

1. **Validation bounds fixed:** Restaurant cap at 25 (was 50 or unbounded)
2. **Volume factor cap reduced:** 4.0x for restaurants with 2000+ reviews (was 6.0x)
3. **Safety checks added:** Ensure restaurants don't exceed 25 after location multipliers
4. **Data consistency:** Loading screen and report page use same priority order
5. **Validation logging:** Console logs when bounds are applied (JavaScript implementations)

## Documentation Files

### Quick Reference

- **`TEAM_ESTIMATION_ai/QUICK_REFERENCE.md`** - Quick lookup for validation bounds, volume factor caps, code locations, debugging scenarios

### Detailed Documentation

- **`TEAM_ESTIMATION_CURRENT_LOGIC.md`** - Complete implementation details for all 4 implementations
- **`TEAM_ESTIMATION_ENHANCED_MODEL.md`** - Enhanced model design and formulas
- **`TEAM_ESTIMATION_DATA_FLOW.md`** - Data flow paths and storage locations
- **`TEAM_ESTIMATION_INCONSISTENCIES.md`** - Historical inconsistencies (now resolved)

### Historical Documentation

- **`TEAM_ESTIMATION_CHANGELOG.md`** - Complete changelog of all changes with dates, reasons, impact
- **`TEAM_ESTIMATION_IMPROVEMENTS_APPLIED.md`** - Summary of improvements applied
- **`TEAM_ESTIMATION_FINAL_STATUS.md`** - Final implementation status

### Testing & Research

- **`TEAM_ESTIMATION_TESTING_GUIDE.md`** - Testing infrastructure and procedures
- **`TEAM_ESTIMATION_TEST_RESULTS.md`** - Test results and accuracy metrics
- **`TEAM_ESTIMATION_RESEARCH.md`** - Research findings and industry benchmarks

## Best Practices

### When Modifying Team Estimation Logic

1. **Update all implementations:** Changes must be made in all 4 locations
2. **Maintain consistency:** All implementations must use same formulas, bounds, and caps
3. **Test edge cases:** Verify with very high/low review counts, missing data, different business types
4. **Update documentation:** Update changelog and all related documentation files
5. **Add logging:** Include console logging for debugging when validation bounds are applied
6. **Verify data consistency:** Ensure loading screen and report page show same values

### Validation Bounds Guidelines

- **Restaurants:** Maximum 25 employees (realistic for single-location operations)
- **Cafes:** Maximum 15 employees (smaller operations)
- **Bars:** Maximum 25 employees (similar to restaurants)
- **Stores:** Maximum 30 employees (can scale larger)
- **Hospitals:** Maximum 60 employees (larger operations)
- **Pharmacies:** Maximum 20 employees (moderate size)

### Volume Factor Guidelines

- **High review counts:** Reduce cap for restaurants with 2000+ reviews to prevent unrealistic inflation
- **Other businesses:** Can use higher cap (6.0x) as they may scale differently
- **Always validate:** Apply safety checks after location multipliers to ensure final values are realistic

## Related ShiftOps Documentation

- **`SHIFTOPS_COMPONENTS.md`** - All classes and methods documentation
- **`SHIFTOPS_DATA_STRUCTURES.md`** - Complete data structures reference
- **`SHIFTOPS_DEVELOPER_GUIDE.md`** - Developer guide with best practices
- **`SHIFTOPS_ARCHITECTURE.md`** - System architecture documentation

## Quick Links

- **Changelog** → `TEAM_ESTIMATION_CHANGELOG.md`
- **Quick Reference** → `TEAM_ESTIMATION_ai/QUICK_REFERENCE.md`
- **Current Logic** → `TEAM_ESTIMATION_CURRENT_LOGIC.md`
- **Enhanced Model** → `TEAM_ESTIMATION_ENHANCED_MODEL.md`