turash/bugulma/frontend/ORGANIZATION_REFACTORING_SUMMARY.md

Frontend Organization Refactoring Summary

Overview

Refactored frontend to align with backend architecture where Organization is the main entity and Business is a subtype for commercial organizations. Organizations can be governmental, cultural, religious, educational, infrastructure, healthcare, or other types.

Changes Implemented

1. Organization Subtype System ✅

Created: schemas/organizationSubtype.ts

• Defines organization subtypes: commercial, cultural, government, religious, educational, infrastructure, healthcare, other
• Utility functions:
  • canParticipateInResourceMatching() - Only commercial organizations participate
  • getOrganizationSubtypeLabel() - Display labels
  • inferSubtypeFromHistoricBuilding() - Helper for historic data

Updated: schemas/backend/organization.ts

• Added Subtype field to backendOrganizationSchema
• Defaults to 'commercial' for backwards compatibility
• Added subtype to createOrganizationRequestSchema

2. Site Schema Updates ✅

Updated: schemas/backend/site.ts

• Changed OwnerBusinessID → OwnerOrganizationID
• Changed owner_business_id → owner_organization_id in request schema
• Sites now correctly belong to Organizations (any type)

3. Resource Flow Schema Updates ✅

Updated: schemas/backend/resource-flow.ts

• Changed BusinessID → OrganizationID
• Changed business_id → organization_id in request schema
• Resource flows belong to Organizations (any type)

4. API Service Updates ✅

Updated: services/sites-api.ts

• Renamed getSitesByBusiness() → getSitesByOrganization()
• Updated endpoint: /api/sites/business/:id → /api/sites/organization/:id
• Added deprecated alias for backwards compatibility

Updated: services/resources-api.ts

• Renamed getResourceFlowsByBusiness() → getResourceFlowsByOrganization()
• Updated endpoint: /api/resources/business/:id → /api/resources/organization/:id
• Added deprecated alias for backwards compatibility

5. Hook Updates ✅

Updated: hooks/api/useSitesAPI.ts

• Renamed useSitesByBusiness() → useSitesByOrganization()
• Updated query keys: byBusiness → byOrganization
• Added deprecated alias for backwards compatibility

Updated: hooks/api/useResourcesAPI.ts

• Renamed useResourceFlowsByBusiness() → useResourceFlowsByOrganization()
• Updated query keys: byBusiness → byOrganization
• Added deprecated alias for backwards compatibility

Updated: hooks/map/useOrganizationSites.ts

• Updated to use getSitesByOrganization()
• Updated query keys to use 'organization' instead of 'business'

Updated: hooks/map/useSitesByBounds.ts

• Changed site.OwnerBusinessID → site.OwnerOrganizationID

6. Component Updates ✅

Updated: components/organization/OrganizationContent.tsx

• Changed businessId prop → organizationId in ResourceFlowList

Updated: components/resource-flow/ResourceFlowList.tsx

• Changed businessId prop → organizationId
• Updated to use useResourceFlowsByOrganization()

Updated: components/add-organization/AddOrganizationWizard.tsx

• Changed owner_business_id → owner_organization_id in site creation

7. Mapper Updates ✅

Updated: lib/resource-flow-mapper.ts

• Changed businessId parameter → organizationId
• Changed business_id → organization_id in resource flow creation

Backwards Compatibility

All deprecated functions are kept as aliases to prevent breaking changes:

• getSitesByBusiness() → getSitesByOrganization()
• getResourceFlowsByBusiness() → getResourceFlowsByOrganization()
• useSitesByBusiness() → useSitesByOrganization()
• useResourceFlowsByBusiness() → useResourceFlowsByOrganization()

Next Steps (Backend Alignment Required)

Backend API Endpoints Need Updates:

1. Site Endpoints:

   • /api/sites/business/:id → /api/sites/organization/:id
   • Update Site domain model: OwnerBusinessID → OwnerOrganizationID

2. Resource Flow Endpoints:

   • /api/resources/business/:id → /api/resources/organization/:id
   • Update ResourceFlow domain model: BusinessID → OrganizationID

3. Organization Domain:

   • Add Subtype field to Organization struct
   • Default to "commercial" for existing records

4. Matching Service:

   • Filter to only consider organizations with Subtype == "commercial"
   • Update matching logic to check organization subtype

Frontend Remaining Tasks:

1. Add Organization Subtype Filtering:

   • Filter organizations by subtype in UI
   • Only show commercial organizations in resource matching
   • Display subtype badges/labels

2. Update Matching Logic:

   • Ensure symbiosis matching only considers commercial organizations
   • Add subtype checks in matching hooks

3. UI Enhancements:

   • Display organization subtype in organization cards
   • Add subtype filter in map view
   • Show appropriate UI for different organization types

Architecture Benefits

✅ Correct Entity Model: Organization is the parent entity, Business is a subtype ✅ Supports Multiple Types: Governmental, cultural, religious, educational organizations ✅ Clear Resource Matching Scope: Only commercial organizations participate ✅ Extensible: Easy to add new organization types ✅ Type Safety: Proper TypeScript types for subtypes ✅ Backwards Compatible: Deprecated aliases prevent breaking changes

Files Modified

Schemas:

• schemas/organizationSubtype.ts (new)
• schemas/backend/organization.ts
• schemas/backend/site.ts
• schemas/backend/resource-flow.ts

Services:

• services/sites-api.ts
• services/resources-api.ts

Hooks:

• hooks/api/useSitesAPI.ts
• hooks/api/useResourcesAPI.ts
• hooks/map/useOrganizationSites.ts
• hooks/map/useSitesByBounds.ts

Components:

• components/organization/OrganizationContent.tsx
• components/resource-flow/ResourceFlowList.tsx
• components/add-organization/AddOrganizationWizard.tsx

Utilities:

• lib/resource-flow-mapper.ts

Testing Checklist

• Verify sites can be created with organization IDs
• Verify resource flows can be created with organization IDs
• Test organization subtype filtering
• Verify matching only considers commercial organizations
• Test backwards compatibility with deprecated functions
• Verify map markers work with updated site schema

Migration Notes

When backend is updated:

1. Backend will return OwnerOrganizationID instead of OwnerBusinessID
2. Backend will return OrganizationID instead of BusinessID in resource flows
3. Backend will include Subtype field in Organization responses
4. Frontend deprecated aliases can be removed after backend migration