turash/bugulma/frontend/INTEGRATION_SUMMARY.md

Frontend-Backend Integration Summary

Overview

The frontend has been successfully aligned with the enhanced Go backend API. This document summarizes the changes and provides guidance for continued development.

Completed Integration

1. API Infrastructure ✅

• API Client (lib/api-client.ts): Base HTTP client with JWT authentication
• Service Layer (services/*-api.ts): Type-safe API service functions
• React Query Hooks (hooks/api/*.ts): Data fetching and mutations with caching

2. Data Models ✅

• Backend Schemas (schemas/backend/*.ts): Zod schemas matching backend domain models
  • Organization
  • Site
  • ResourceFlow
  • Match

3. Updated Components ✅

• OrganizationContext: Now uses API hooks instead of local data
• OrganizationPage: Integrated ResourceFlowList and MatchesList
• ResourceFlowList: New component to display resource flows (replaces needs/offers)
• ResourceFlowCard: Individual resource flow display
• MatchesList: Displays matches for a resource
• MatchCard: Individual match display with scoring and economic data

4. Authentication ✅

• AuthContext: Updated to use API client's login function
• JWT token management integrated
• Automatic token inclusion in API requests

Key Changes

Breaking Changes

1. Organization Model:

   • Frontend's previous model had embedded needs and offers
   • These are now separate ResourceFlow entities
   • Use useResourceFlowsByBusiness(businessId) to fetch resource flows

2. Field Naming:

   • Backend uses Go's default JSON encoding (capitalized: ID, Name, etc.)
   • Nested structs use snake_case (temperature_celsius, cost_in, etc.)
   • Frontend schemas match this convention

3. Data Flow:

   • Organizations fetched from API via useOrganizations() hook
   • Resource flows fetched separately via useResourceFlowsByBusiness()
   • Matches fetched via useFindMatches(resourceId)

Component Usage

Displaying Resource Flows

import ResourceFlowList from '@/components/resource-flow/ResourceFlowList';

<ResourceFlowList
  businessId={organizationId}
  onViewMatches={(resourceId) => setSelectedResourceId(resourceId)}
/>;

Displaying Matches

import MatchesList from '@/components/matches/MatchesList';

<MatchesList resourceId={selectedResourceId} maxDistanceKm={30} minScore={0.3} limit={10} />;

Creating Organizations

import { useCreateOrganization } from '@/hooks/api';

const createOrg = useCreateOrganization();

await createOrg.mutateAsync({
  name: 'Organization Name',
  sector: '35.30',
  description: 'Description',
});

Remaining Tasks

High Priority

1. ResourceFlowForm: Create form component for creating/editing resource flows
2. MapView Integration: Ensure organizations from API have location data for map display
3. AdminPage: Update organization table to use API hooks
4. Site Management: Create components for managing sites

Medium Priority

1. Error Handling: Add comprehensive error handling and user feedback
2. Loading States: Improve loading indicators throughout
3. Optimistic Updates: Add optimistic updates for better UX
4. Form Validation: Enhance form validation with backend-aligned schemas

Low Priority

1. Match Details Modal: Create detailed match view modal
2. Resource Flow Editing: Add edit functionality for resource flows
3. Bulk Operations: Add bulk create/edit for resource flows
4. Export/Import: Add data export/import functionality

Testing Checklist

• Organizations load from API
• Resource flows display correctly
• Matches can be found and displayed
• Authentication works end-to-end
• Map view displays organizations with locations
• Admin page organization table works
• Error states are handled gracefully
• Loading states display correctly

Migration Guide for Existing Components

Before (Local Data)

const { organizations } = useOrganizations();
const org = organizations.find((o) => o.id === id);

After (API)

const { data: organizations, isLoading } = useOrganizations();
const { data: org } = useOrganization(id);

Before (Embedded Needs/Offers)

<OrganizationNeedsOffers organization={organization} />

After (Separate Resource Flows)

<ResourceFlowList businessId={organization.ID} onViewMatches={handleViewMatches} />

Notes

• The backend API uses capitalized field names for main structs
• Nested structs use snake_case JSON tags
• All API responses are validated with Zod schemas
• React Query handles caching, refetching, and state management
• Authentication tokens are stored in localStorage
• API base URL can be configured via VITE_API_BASE_URL env variable

Next Steps

1. Test the integration with a running backend
2. Adjust field names if backend JSON encoding differs
3. Add missing translation keys for new components
4. Create ResourceFlowForm component
5. Update remaining components to use API hooks