# Frontend Architecture

## User-Friendly Abstraction Layer

The frontend uses **business-friendly terminology** that is intuitive for users, while the backend uses **technical terminology** optimized for the matching engine.

### UI Layer (User-Friendly)

- **Needs**: What the organization requires (e.g., "Heat", "Water", "Materials")
- **Offers**: What the organization provides (e.g., "Waste heat", "Steam", "By-products")
- Simple, clear language that business users understand

### Backend Layer (Technical)

- **ResourceFlow**: Technical entity with `direction` ('input' or 'output')
- **ResourceType**: Enum values ('heat', 'water', 'steam', 'CO2', etc.)
- Optimized for matching algorithms and data processing

### Translation Layer

The `lib/resource-flow-mapper.ts` converts between these layers:

```typescript
// User enters: "I need 100 kg of materials"
// Frontend stores: { resource_name: "materials", quantity: "100 kg", direction: "need" }
// Mapper converts to: { direction: "input", type: "materials", quantity: { amount: 100, unit: "kg" } }
```

## Benefits

1. **Better UX**: Users don't need to understand technical concepts like "ResourceFlow" or "input/output"
2. **Clean Separation**: Frontend focuses on user experience, backend focuses on technical implementation
3. **Maintainability**: Changes to backend structure don't require UI changes
4. **Flexibility**: Can improve mapping logic without changing user interface

## Data Flow

```
User Input (Needs/Offers)
    ↓
Form Schema (Zod validation)
    ↓
Organization Form Data
    ↓
Resource Flow Mapper (conversion layer)
    ↓
Backend API (ResourceFlow with direction)
    ↓
Backend Storage & Matching Engine
```

## Type Safety

- **Frontend Types**: User-friendly (`needs`, `offers` with `resource_name`)
- **Backend Types**: Technical (`ResourceFlow` with `Direction`, `Type`)
- **Zod Schemas**: Validate at both layers
- **Runtime Validation**: All API responses validated with Zod