turash/bugulma/frontend/docs/ORGANIZATION_CATEGORIZATION_SYSTEM.md

Organization Categorization System

This document defines a comprehensive, hierarchical categorization system for organizations that enables clean separation, easy filtering, and scalable classification.

System Overview

The categorization system uses a three-tier hierarchical structure:

1. Primary Sectors - Broad industry categories (mutually exclusive)
2. Business Types - Specific business classifications within sectors
3. Service Categories - Functional groupings for filtering and user experience

Primary Sectors

Primary sectors represent the fundamental industry categories. Each organization belongs to exactly one primary sector.

Consumer Services (CONSUMER)

Organizations providing direct services to individual consumers.

Examples:

• Beauty & personal care salons
• Fitness centers and gyms
• Restaurants and cafes
• Retail stores
• Personal service providers (cleaners, tutors)

Professional Services (PROFESSIONAL)

Organizations providing specialized expertise and consulting services.

Examples:

• Legal firms and consultants
• Accounting and financial advisors
• IT consulting and software development
• Marketing and advertising agencies
• Engineering and architectural firms

Healthcare & Wellness (HEALTHCARE)

Organizations focused on medical care, mental health, and physical wellness.

Examples:

• Hospitals and clinics
• Dental practices
• Pharmacies
• Mental health services
• Fitness and wellness centers
• Alternative medicine practitioners

Education & Training (EDUCATION)

Organizations providing learning and skill development services.

Examples:

• Schools and universities
• Training centers and academies
• Tutoring services
• Professional development programs
• Language schools

Food & Hospitality (FOOD_HOSPITALITY)

Organizations in the food service and accommodation industry.

Examples:

• Restaurants and cafes
• Hotels and lodging
• Food delivery services
• Catering companies
• Bars and entertainment venues

Retail & Commerce (RETAIL)

Organizations engaged in selling goods to consumers and businesses.

Examples:

• Department stores
• Specialty shops
• Online retailers
• Wholesale distributors
• Marketplaces and bazaars

Manufacturing & Industry (MANUFACTURING)

Organizations producing physical goods and industrial products.

Examples:

• Manufacturing facilities
• Construction companies
• Agricultural producers
• Energy production companies
• Raw material suppliers

Technology & Innovation (TECHNOLOGY)

Organizations in software, hardware, telecommunications, and tech services.

Examples:

• Software development companies
• IT service providers
• Telecommunications companies
• Hardware manufacturers
• Tech startups and innovation hubs

Financial Services (FINANCIAL)

Organizations providing banking, investment, and financial management services.

Examples:

• Banks and credit unions
• Investment firms
• Insurance companies
• Financial planning services
• Payment processors

Government & Public Services (GOVERNMENT)

Public sector organizations and government-related services.

Examples:

• Government offices and agencies
• Public utilities
• Municipal services
• Law enforcement and emergency services
• Public transportation

Community & Non-Profit (COMMUNITY)

Religious, cultural, and community organizations.

Examples:

• Religious institutions
• Cultural centers and museums
• Non-profit organizations
• Community centers
• Social service providers

Business Types

Business types provide more specific classification within each sector. These are not mutually exclusive within a sector but help define the specific nature of the business.

Service-Based Types

• direct_service - Direct consumer services (salons, fitness, personal care)
• professional_service - Expert consulting and professional services
• educational_service - Teaching and training services
• healthcare_service - Medical and wellness services
• hospitality_service - Accommodation and food service
• maintenance_service - Repair and maintenance services

Product-Based Types

• retail_goods - Consumer goods retail
• wholesale_goods - Bulk goods distribution
• manufactured_goods - Physical product manufacturing
• digital_products - Software and digital products
• food_products - Food production and distribution

Institutional Types

• educational_institution - Schools, universities, academies
• medical_institution - Hospitals, clinics, healthcare facilities
• government_office - Public administration offices
• religious_institution - Churches, temples, religious centers
• non_profit_organization - Charitable and community organizations

Commercial Types

• local_business - Neighborhood businesses
• chain_business - Multi-location chains
• online_business - E-commerce and digital-first businesses
• b2b_services - Business-to-business services
• franchise - Franchise operations

Service Categories

Service categories enable cross-sector filtering based on functional needs and user requirements.

Essential Services

Services critical for daily living and emergency needs.

• Emergency medical care
• Law enforcement and safety
• Public utilities (water, electricity, gas)
• Emergency shelter and food services
• Crisis counseling and support

Daily Living

Services supporting everyday routines and quality of life.

• Grocery stores and food services
• Personal care and hygiene
• Transportation services
• Banking and financial services
• Household services (cleaning, maintenance)

Health & Wellness

Services promoting physical and mental well-being.

• Medical facilities and practitioners
• Fitness centers and sports facilities
• Mental health services
• Nutrition and dietary services
• Alternative medicine and wellness centers

Education & Development

Services for learning and personal growth.

• Schools and educational institutions
• Professional training programs
• Skill development workshops
• Career counseling and placement
• Language and cultural education

Entertainment & Leisure

Services for recreation and social activities.

• Restaurants and dining establishments
• Entertainment venues (theaters, cinemas)
• Sports facilities and recreational centers
• Cultural institutions (museums, galleries)
• Event spaces and party services

Professional & Business

Services supporting career and business activities.

• Legal and accounting services
• Business consulting and advisory
• IT and technology services
• Marketing and advertising services
• Office and administrative services

Community & Social

Services fostering community connection and support.

• Religious and spiritual centers
• Community centers and social clubs
• Non-profit organizations and charities
• Volunteer coordination services
• Cultural and heritage preservation

Mapping Rules

Sector Assignment Rules

1. Single Sector Only: Each organization belongs to exactly one primary sector
2. Primary Purpose: Assign based on the organization's main business purpose
3. Revenue Source: Consider primary revenue-generating activity
4. Target Audience: Factor in whether serving consumers, businesses, or government

Business Type Assignment Rules

1. Multiple Types Allowed: Organizations can have multiple business types
2. Specific Characteristics: Choose types that best describe specific aspects
3. Operational Model: Consider how the business operates (local, chain, online, etc.)
4. Service vs Product Focus: Distinguish between service and product-oriented businesses

Service Category Assignment Rules

1. Functional Purpose: Based on what need the organization fulfills
2. User-Centric: Focused on how users would search for or need these services
3. Multiple Categories: Organizations can serve multiple functional purposes
4. Cross-Sector: Categories span across different sectors

Filtering Strategy

Primary Filtering Dimensions

By Sector (Industry-based filtering):

• Find all healthcare organizations
• Show manufacturing companies
• Locate educational institutions

By Business Type (Operational filtering):

• Find all local businesses in an area
• Show chain restaurants
• Locate professional service providers

By Service Category (Need-based filtering):

• Find emergency services
• Show daily living essentials
• Locate entertainment options

Advanced Filtering Combinations

Multi-dimensional filters:

• Healthcare services that are local businesses
• Professional services in education sector
• Retail businesses providing essential daily services

Geographic + Categorical:

• Essential services within 2km
• Professional services in specific neighborhoods
• Educational institutions by sector and type

Implementation Guidelines

Data Structure

interface OrganizationCategory {
  primarySector: PrimarySector;
  businessTypes: BusinessType[];
  serviceCategories: ServiceCategory[];
}

Database Schema Considerations

• Primary sector as required field
• Business types as array/tags
• Service categories as array/tags
• Validation rules to ensure logical consistency

UI/UX Considerations

• Primary filtering by service categories (user needs)
• Secondary filtering by sectors (industry expertise)
• Tertiary filtering by business types (specific preferences)
• Progressive disclosure of filter options

Migration Strategy

From Current System

1. Map existing sectors to new primary sectors
2. Translate subtypes to appropriate business types
3. Add service categories based on functional purpose
4. Validate mappings through testing and user feedback

Data Quality Improvements

1. Consistency checks: Ensure logical sector-business type relationships
2. Completeness validation: Require all three categorization levels
3. User testing: Validate that filtering meets user needs
4. Iterative refinement: Adjust categories based on real usage patterns

Benefits of New System

For Users

• Intuitive filtering: Find services based on needs, not technical categories
• Comprehensive results: Multi-dimensional search captures all relevant organizations
• Progressive refinement: Start broad, narrow down based on preferences

For Administrators

• Scalable structure: Easy to add new categories without breaking existing ones
• Data quality: Clear rules prevent inconsistent categorization
• Analytics ready: Structured data enables better insights and reporting

For Developers

• Clean architecture: Separation of concerns between sectors, types, and categories
• Flexible querying: Support for complex filter combinations
• Maintainable code: Clear categorization logic and validation rules

Future Extensions

Additional Dimensions

• Size categories: Small local businesses vs. large enterprises
• Accessibility features: Services accommodating specific needs
• Sustainability ratings: Environmentally conscious businesses
• Quality certifications: Accredited and certified organizations

Integration Points

• User preferences: Personalized filtering based on user profiles
• Time-based services: Hours of operation and availability filtering
• Rating and review integration: Quality-based filtering options

---

Appendix: Current System Analysis

Issues with Current System

1. Sector/Subtype confusion: 54.6% of organizations have identical sector and subtype values
2. Limited filtering dimensions: Only two levels of categorization
3. User-centric gaps: Categories not aligned with how users search for services
4. Scalability concerns: Adding new categories breaks existing logic

Migration Mapping Examples

Current → New System:

• retail/retail → RETAIL sector, retail_goods type, daily_living category
• healthcare/healthcare → HEALTHCARE sector, medical_institution type, essential_services category
• services/professional_services → PROFESSIONAL sector, professional_service type, professional_business category

This new system provides the clean separation and easy filtering requested while maintaining backward compatibility during migration.