# Organization Migration Mapping Guide

This document provides detailed mapping from the current sector/subtype system to the new comprehensive categorization system.

## Migration Overview

**Source Data**: 1,280 organizations with sector/subtype combinations
**Target System**: Three-tier hierarchy (Primary Sector → Business Types → Service Categories)

## Sector Mapping Table

| Current Sector | Count | New Primary Sector | Rationale |
|----------------|-------|-------------------|-----------|
| `retail` | 248 | **RETAIL_COMMERCE** | Direct consumer goods retail |
| `healthcare` | 134 | **HEALTHCARE_WELLNESS** | Medical and healthcare services |
| `services` | 126 | **PROFESSIONAL_SERVICES** | Professional and consulting services |
| `automotive` | 119 | **TRANSPORTATION_LOGISTICS** | Automotive and transportation |
| `food_beverage` | 94 | **FOOD_HOSPITALITY** | Food and beverage services |
| `beauty_wellness` | 79 | **CONSUMER_SERVICES** | Personal care and wellness |
| `religious` | 86 | **COMMUNITY_RELIGIOUS** | Religious and community organizations |
| `education` | 117 | **EDUCATION_TRAINING** | Educational institutions |
| `energy` | 46 | **MANUFACTURING_INDUSTRY** | Energy production and utilities |
| `construction` | 31 | **MANUFACTURING_INDUSTRY** | Construction and building |
| `entertainment` | 25 | **COMMUNITY_RELIGIOUS** | Cultural and entertainment |
| `financial` | 43 | **PROFESSIONAL_SERVICES** | Financial services |
| `hospitality` | 24 | **FOOD_HOSPITALITY** | Accommodation services |
| `manufacturing` | 18 | **MANUFACTURING_INDUSTRY** | Manufacturing facilities |
| `government` | 17 | **GOVERNMENT_PUBLIC** | Government offices |
| `furniture` | 32 | **RETAIL_COMMERCE** | Furniture retail |
| `other` | 28 | *(context-dependent)* | Requires individual review |
| `sports` | 2 | **COMMUNITY_RELIGIOUS** | Sports and recreation |
| `technology` | 2 | **PROFESSIONAL_SERVICES** | Technology services |
| `agriculture` | 2 | **AGRICULTURE_RESOURCES** | Agricultural businesses |

## Detailed Subtype Mappings

### RETAIL_COMMERCE Sector (248 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `retail/retail` | 202 | `retail_store` | `shopping_retail`, `daily_living` | Standard retail stores |
| `retail/commercial` | 46 | `retail_store`, `online_business` | `shopping_retail` | Commercial retail operations |

### HEALTHCARE_WELLNESS Sector (134 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `healthcare/healthcare` | 134 | `healthcare_facility` | `health_medical`, `essential_services` | All healthcare providers |

### PROFESSIONAL_SERVICES Sector (171 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `services/professional_services` | 19 | `professional_service` | `professional_business` | Consulting and professional services |
| `services/commercial` | 87 | `professional_service` | `professional_business` | Business services |
| `services/healthcare` | 4 | `professional_service` | `health_medical` | Healthcare consulting |
| `services/other` | 4 | `professional_service` | `specialized_services` | Specialized consulting |
| `services/personal_services` | 12 | `direct_service` | `personal_care` | Personal professional services |
| `financial/financial` | 41 | `professional_service` | `financial_services` | Financial services |
| `financial/commercial` | 2 | `professional_service` | `financial_services` | Commercial finance |
| `technology/technology` | 2 | `professional_service` | `professional_business` | Tech services |

### TRANSPORTATION_LOGISTICS Sector (119 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `automotive/automotive` | 76 | `transportation_service` | `transportation` | Automotive services |
| `automotive/commercial` | 7 | `transportation_service` | `transportation` | Commercial vehicle services |
| `automotive/infrastructure` | 6 | `transportation_service` | `transportation` | Transport infrastructure |
| `automotive/transportation` | 15 | `transportation_service` | `transportation` | Transportation services |

### FOOD_HOSPITALITY Sector (118 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `food_beverage/food_beverage` | 84 | `food_establishment` | `food_dining`, `daily_living` | Restaurants and food service |
| `food_beverage/commercial` | 6 | `food_establishment` | `food_dining` | Commercial food operations |
| `food_beverage/other` | 4 | `food_establishment` | `food_dining` | Other food services |
| `hospitality/commercial` | 1 | `hospitality_venue` | `food_dining` | Commercial hospitality |
| `hospitality/educational` | 7 | `hospitality_venue` | `entertainment_leisure` | Educational hospitality |
| `hospitality/hospitality` | 16 | `hospitality_venue` | `food_dining` | Hotels and lodging |

### CONSUMER_SERVICES Sector (79 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `beauty_wellness/personal_services` | 79 | `direct_service` | `personal_care` | Beauty and wellness services |

### COMMUNITY_RELIGIOUS Sector (113 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `religious/religious` | 65 | `religious_institution` | `community_religious` | Religious institutions |
| `religious/cultural` | 9 | `religious_institution` | `community_religious` | Cultural religious sites |
| `religious/government` | 12 | `religious_institution` | `community_religious` | Religious government relations |
| `entertainment/cultural` | 18 | `non_profit_organization` | `entertainment_leisure` | Cultural entertainment |
| `entertainment/commercial` | 1 | `hospitality_venue` | `entertainment_leisure` | Commercial entertainment |
| `entertainment/other` | 8 | `hospitality_venue` | `entertainment_leisure` | Other entertainment |
| `sports/cultural` | 2 | `non_profit_organization` | `entertainment_leisure` | Sports organizations |

### EDUCATION_TRAINING Sector (117 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `education/educational` | 104 | `educational_institution` | `education_learning` | Educational institutions |
| `education/commercial` | 1 | `educational_institution` | `education_learning` | Commercial education |
| `education/cultural` | 1 | `educational_institution` | `education_learning` | Cultural education |
| *(empty sector)* | 11 | *(needs review)* | *(needs review)* | Organizations without sector |

### MANUFACTURING_INDUSTRY Sector (95 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `manufacturing/commercial` | 2 | `manufacturing_facility` | `specialized_services` | Commercial manufacturing |
| `manufacturing/manufacturing` | 16 | `manufacturing_facility` | `specialized_services` | Manufacturing facilities |
| `construction/commercial` | 7 | `construction_contractor` | `home_services` | Commercial construction |
| `construction/manufacturing` | 1 | `construction_contractor` | `home_services` | Construction manufacturing |
| `construction/professional_services` | 26 | `construction_contractor` | `home_services` | Construction professionals |
| `construction/retail` | 8 | `construction_contractor` | `home_services` | Construction retail |
| `energy/commercial` | 1 | `manufacturing_facility` | `essential_services` | Commercial energy |
| `energy/energy` | 41 | `manufacturing_facility` | `essential_services` | Energy production |
| `energy/manufacturing` | 5 | `manufacturing_facility` | `essential_services` | Energy manufacturing |

### GOVERNMENT_PUBLIC Sector (17 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `government/government` | 17 | `government_office` | `government_services` | Government offices |

### AGRICULTURE_RESOURCES Sector (2 organizations)

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `agriculture/manufacturing` | 2 | `agricultural_business` | `specialized_services` | Agricultural manufacturing |

### OTHER Sector (28 organizations) - Requires Individual Review

| Current Combination | Count | Business Types | Service Categories | Notes |
|---------------------|-------|----------------|-------------------|-------|
| `other/cultural` | 6 | *(individual review)* | *(individual review)* | Cultural organizations |
| `other/educational` | 17 | *(individual review)* | *(individual review)* | Educational services |
| `other/other` | 5 | *(individual review)* | *(individual review)* | Miscellaneous |

## Migration Logic Implementation

### TypeScript Migration Function

```typescript
interface LegacyOrganization {
  sector: string | null;
  subtype: string;
}

interface NewOrganizationCategory {
  primarySector: string;
  businessTypes: string[];
  serviceCategories: string[];
}

function migrateOrganizationCategory(legacy: LegacyOrganization): NewOrganizationCategory {
  const { sector, subtype } = legacy;

  // Handle empty sector case
  if (!sector) {
    return {
      primarySector: 'NEEDS_REVIEW',
      businessTypes: [],
      serviceCategories: []
    };
  }

  // Sector mapping
  const sectorMap: Record<string, string> = {
    'retail': 'RETAIL_COMMERCE',
    'healthcare': 'HEALTHCARE_WELLNESS',
    'services': 'PROFESSIONAL_SERVICES',
    'automotive': 'TRANSPORTATION_LOGISTICS',
    'food_beverage': 'FOOD_HOSPITALITY',
    'beauty_wellness': 'CONSUMER_SERVICES',
    'religious': 'COMMUNITY_RELIGIOUS',
    'education': 'EDUCATION_TRAINING',
    'energy': 'MANUFACTURING_INDUSTRY',
    'construction': 'MANUFACTURING_INDUSTRY',
    'entertainment': 'COMMUNITY_RELIGIOUS',
    'financial': 'PROFESSIONAL_SERVICES',
    'hospitality': 'FOOD_HOSPITALITY',
    'manufacturing': 'MANUFACTURING_INDUSTRY',
    'government': 'GOVERNMENT_PUBLIC',
    'furniture': 'RETAIL_COMMERCE',
    'sports': 'COMMUNITY_RELIGIOUS',
    'technology': 'PROFESSIONAL_SERVICES',
    'agriculture': 'AGRICULTURE_RESOURCES',
    'other': 'NEEDS_REVIEW'
  };

  // Subtype-specific business type and service category mappings
  const subtypeMappings: Record<string, { businessTypes: string[], serviceCategories: string[] }> = {
    // Retail combinations
    'retail': {
      businessTypes: ['retail_store'],
      serviceCategories: ['shopping_retail', 'daily_living']
    },
    // Healthcare
    'healthcare': {
      businessTypes: ['healthcare_facility'],
      serviceCategories: ['health_medical', 'essential_services']
    },
    // Professional services
    'professional_services': {
      businessTypes: ['professional_service'],
      serviceCategories: ['professional_business']
    },
    'commercial': {
      businessTypes: ['professional_service'],
      serviceCategories: ['professional_business']
    },
    // Personal services
    'personal_services': {
      businessTypes: ['direct_service'],
      serviceCategories: ['personal_care']
    },
    // Food and beverage
    'food_beverage': {
      businessTypes: ['food_establishment'],
      serviceCategories: ['food_dining', 'daily_living']
    },
    // Automotive and transportation
    'automotive': {
      businessTypes: ['transportation_service'],
      serviceCategories: ['transportation']
    },
    'transportation': {
      businessTypes: ['transportation_service'],
      serviceCategories: ['transportation']
    },
    // Educational
    'educational': {
      businessTypes: ['educational_institution'],
      serviceCategories: ['education_learning']
    },
    // Religious and community
    'religious': {
      businessTypes: ['religious_institution'],
      serviceCategories: ['community_religious']
    },
    'cultural': {
      businessTypes: ['non_profit_organization'],
      serviceCategories: ['entertainment_leisure']
    },
    // Manufacturing and construction
    'manufacturing': {
      businessTypes: ['manufacturing_facility'],
      serviceCategories: ['specialized_services']
    },
    // Energy
    'energy': {
      businessTypes: ['manufacturing_facility'],
      serviceCategories: ['essential_services']
    },
    // Hospitality
    'hospitality': {
      businessTypes: ['hospitality_venue'],
      serviceCategories: ['food_dining']
    },
    // Financial
    'financial': {
      businessTypes: ['professional_service'],
      serviceCategories: ['financial_services']
    },
    // Government
    'government': {
      businessTypes: ['government_office'],
      serviceCategories: ['government_services']
    },
    // Technology
    'technology': {
      businessTypes: ['professional_service'],
      serviceCategories: ['professional_business']
    },
    // Infrastructure
    'infrastructure': {
      businessTypes: ['transportation_service'],
      serviceCategories: ['transportation']
    },
    // Other
    'other': {
      businessTypes: [],
      serviceCategories: ['specialized_services']
    }
  };

  const primarySector = sectorMap[sector] || 'NEEDS_REVIEW';
  const subtypeMapping = subtypeMappings[subtype] || { businessTypes: [], serviceCategories: [] };

  return {
    primarySector,
    businessTypes: subtypeMapping.businessTypes,
    serviceCategories: subtypeMapping.serviceCategories
  };
}
```

## Migration Statistics

### By Primary Sector Distribution

| New Primary Sector | Organizations | Percentage |
|-------------------|---------------|------------|
| PROFESSIONAL_SERVICES | 171 | 13.4% |
| RETAIL_COMMERCE | 248 | 19.4% |
| HEALTHCARE_WELLNESS | 134 | 10.5% |
| EDUCATION_TRAINING | 117 | 9.1% |
| TRANSPORTATION_LOGISTICS | 119 | 9.3% |
| FOOD_HOSPITALITY | 118 | 9.2% |
| CONSUMER_SERVICES | 79 | 6.2% |
| COMMUNITY_RELIGIOUS | 113 | 8.8% |
| MANUFACTURING_INDUSTRY | 95 | 7.4% |
| GOVERNMENT_PUBLIC | 17 | 1.3% |
| AGRICULTURE_RESOURCES | 2 | 0.2% |
| NEEDS_REVIEW | 45 | 3.5% | (17 empty + 28 other)
| **TOTAL** | **1,280** | **100%** |

### Service Category Distribution

| Service Category | Organizations | Primary Use Case |
|------------------|---------------|------------------|
| shopping_retail | 248 | Finding stores and shops |
| professional_business | 171 | Business services and consulting |
| health_medical | 138 | Medical care and healthcare |
| transportation | 119 | Getting around and logistics |
| food_dining | 118 | Restaurants and food services |
| education_learning | 117 | Schools and learning |
| community_religious | 113 | Community and spiritual services |
| daily_living | 286 | Everyday necessities |
| essential_services | 175 | Critical services |
| personal_care | 91 | Beauty and personal services |
| specialized_services | 123 | Niche and expert services |
| entertainment_leisure | 29 | Fun and recreation |
| financial_services | 43 | Banking and money |
| government_services | 17 | Public services |
| home_services | 42 | Property and home services |

## Quality Assurance Checks

### Pre-Migration Validation
- [ ] All 1,280 organizations accounted for
- [ ] Sector distribution matches expected counts
- [ ] No organizations lost in mapping
- [ ] Edge cases (empty sectors) properly flagged

### Post-Migration Validation
- [ ] Each organization has exactly one primary sector
- [ ] Business types array is populated
- [ ] Service categories align with primary sector
- [ ] Icon mappings work for all categories
- [ ] Filtering returns expected results

### Performance Validation
- [ ] Database migration completes within time limits
- [ ] Query performance maintained or improved
- [ ] Application startup time unaffected
- [ ] Memory usage within acceptable limits

## Rollback Strategy

### Phase 1: Data Preservation
1. **Backup current data**: Create full backup before migration
2. **Dual schema**: Keep old columns during transition
3. **Gradual rollout**: Migrate in batches with monitoring

### Phase 2: Rollback Execution
1. **Restore old columns**: Revert to sector/subtype system
2. **Clear new data**: Remove migrated categorization
3. **Application rollback**: Deploy previous version
4. **Data verification**: Ensure no data loss

### Phase 3: Analysis & Recovery
1. **Issue identification**: Determine migration failure points
2. **Fix root causes**: Address identified problems
3. **Retest migration**: Validate fixes before retry
4. **Gradual re-migration**: Migrate in smaller, monitored batches

---

*This detailed mapping ensures accurate migration from the current mixed system to the new comprehensive categorization system while maintaining data integrity and providing clear migration paths for all edge cases.*