turash/bugulma/frontend/docs/ORGANIZATION_ICONS_MIGRATION_GUIDE.md

# Organization Icons Migration Guide

This guide shows how to migrate from the current sector/subtype system to the new categorization system while maintaining icon compatibility.

## Current vs New System Mapping

### Primary Sector to Icon Mapping

| New Primary Sector | Legacy Sector(s)                    | Recommended Icon             | Rationale                             |
| ------------------ | ----------------------------------- | ---------------------------- | ------------------------------------- |
| CONSUMER           | beauty_wellness, retail (personal)  | `Scissors` or `ShoppingBag`  | Represents personal consumer services |
| PROFESSIONAL       | services (professional_services)    | `Briefcase`                  | Professional expertise                |
| HEALTHCARE         | healthcare                          | `Heart`                      | Medical care and wellness             |
| EDUCATION          | education                           | `GraduationCap`              | Learning and education                |
| FOOD_HOSPITALITY   | food_beverage, hospitality          | `UtensilsCrossed` or `Hotel` | Food and accommodation                |
| RETAIL             | retail                              | `ShoppingBag`                | Consumer goods shopping               |
| MANUFACTURING      | manufacturing, construction, energy | `Factory` or `Construction`  | Production and building               |
| TECHNOLOGY         | technology                          | `Cpu`                        | Technology and innovation             |
| FINANCIAL          | financial                           | `Banknote`                   | Money and finance                     |
| GOVERNMENT         | government                          | `Building`                   | Public administration                 |
| COMMUNITY          | religious, entertainment, sports    | `Church` or `Theater`        | Community and culture                 |

### Business Type to Icon Mapping

| Business Type           | Icon            | Context                  |
| ----------------------- | --------------- | ------------------------ |
| direct_service          | `Scissors`      | Personal care services   |
| professional_service    | `Briefcase`     | Consulting and expertise |
| educational_service     | `GraduationCap` | Teaching and training    |
| healthcare_service      | `Heart`         | Medical services         |
| hospitality_service     | `Hotel`         | Accommodation services   |
| retail_goods            | `ShoppingBag`   | Product sales            |
| manufactured_goods      | `Factory`       | Manufacturing            |
| digital_products        | `Cpu`           | Software and digital     |
| educational_institution | `GraduationCap` | Schools and universities |
| medical_institution     | `Heart`         | Healthcare facilities    |
| government_office       | `Building`      | Public offices           |
| religious_institution   | `Church`        | Places of worship        |
| local_business          | `Building2`     | Local establishments     |
| online_business         | `Cpu`           | Digital businesses       |

### Service Category to Icon Mapping

| Service Category      | Primary Icon    | Alternative Icons              |
| --------------------- | --------------- | ------------------------------ |
| essential_services    | `Heart`         | `Building` (for emergency)     |
| daily_living          | `ShoppingBag`   | `UtensilsCrossed`, `Car`       |
| health_wellness       | `Heart`         | `Scissors` (for personal care) |
| education_development | `GraduationCap` | `Briefcase`                    |
| entertainment_leisure | `Theater`       | `UtensilsCrossed`, `Hotel`     |
| professional_business | `Briefcase`     | `Banknote`, `Cpu`              |
| community_social      | `Church`        | `Theater`, `Building2`         |

## Migration Strategy

### Phase 1: Data Preparation

1. **Analyze current data**: Map existing sector/subtype combinations to new categories
2. **Create migration mapping table**: Document how each organization will transition
3. **Update database schema**: Add new categorization fields while keeping legacy fields

### Phase 2: Icon System Updates

1. **Update icon mapping function**: Modify `getLucideIconForSubtype()` to work with new system
2. **Create fallback logic**: Ensure backward compatibility during transition
3. **Test icon rendering**: Verify all combinations display correctly

### Phase 3: UI Updates

1. **Update filter interfaces**: Implement new filtering based on service categories
2. **Modify search logic**: Support multi-dimensional filtering
3. **Update admin interfaces**: Allow categorization using new system

## Implementation Code Example

```typescript
// New categorization interface
interface OrganizationCategory {
  primarySector: PrimarySector;
  businessTypes: BusinessType[];
  serviceCategories: ServiceCategory[];
}

// Migration function
function migrateOrganizationCategory(
  legacySector: string,
  legacySubtype: string
): OrganizationCategory {
  const mapping = LEGACY_TO_NEW_MAPPING[`${legacySector}/${legacySubtype}`];
  return {
    primarySector: mapping.primarySector,
    businessTypes: mapping.businessTypes,
    serviceCategories: mapping.serviceCategories,
  };
}

// Updated icon selection logic
function getIconForOrganization(category: OrganizationCategory): LucideIcon {
  // Priority: Service Category > Business Type > Primary Sector
  const serviceCategoryIcon = getServiceCategoryIcon(category.serviceCategories[0]);
  if (serviceCategoryIcon) return serviceCategoryIcon;

  const businessTypeIcon = getBusinessTypeIcon(category.businessTypes[0]);
  if (businessTypeIcon) return businessTypeIcon;

  return getPrimarySectorIcon(category.primarySector);
}
```

## Backward Compatibility

### During Migration

- Keep legacy sector/subtype fields in database
- Add new categorization fields alongside existing ones
- Icon function checks new system first, falls back to legacy mapping

### Post-Migration

- Legacy fields can be deprecated after full transition
- Update all data entry points to use new categorization
- Clean up legacy mapping code

## Testing Checklist

- [ ] All current organizations display with appropriate icons
- [ ] New categorization fields work correctly
- [ ] Filtering by service categories functions properly
- [ ] Search results include relevant organizations
- [ ] Admin interface supports new categorization
- [ ] Performance impact is minimal
- [ ] Mobile responsiveness maintained

## Rollback Plan

If issues arise during migration:

1. **Immediate rollback**: Switch back to legacy icon mapping
2. **Data preservation**: Keep new categorization data for future migration
3. **Staged approach**: Migrate in smaller batches to isolate issues
4. **User communication**: Inform users of temporary categorization changes

---

This migration guide ensures smooth transition while maintaining the visual consistency users expect from the current icon system.