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

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

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

### Displaying Matches

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

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

### Creating Organizations

```tsx
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)

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

### After (API)

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

### Before (Embedded Needs/Offers)

```tsx
<OrganizationNeedsOffers organization={organization} />
```

### After (Separate Resource Flows)

```tsx
<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