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

```typescript
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.