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

// 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.