bakery-ia/FRONTEND_API_ANALYSIS_SUMMARY.md

Frontend API Analysis - Executive Summary

Document Location

Complete analysis: /home/user/bakery_ia/FRONTEND_API_TYPES_ANALYSIS.md (1,741 lines)

Quick Overview

1. RECIPE API

File: /home/user/bakery_ia/frontend/src/api/types/recipes.ts Hooks: /home/user/bakery_ia/frontend/src/api/hooks/recipes.ts

Key Types: RecipeCreate, RecipeUpdate, RecipeResponse, RecipeIngredientResponse, RecipeQualityConfiguration

Key Hooks:

• Query: useRecipe, useRecipes, useInfiniteRecipes, useRecipeStatistics, useRecipeCategories, useRecipeFeasibility
• Mutation: useCreateRecipe, useUpdateRecipe, useDeleteRecipe, useArchiveRecipe, useDuplicateRecipe, useActivateRecipe

---

2. SUPPLIER API

File: /home/user/bakery_ia/frontend/src/api/types/suppliers.ts Hooks: /home/user/bakery_ia/frontend/src/api/hooks/suppliers.ts

Key Types:

• Supplier: SupplierCreate, SupplierResponse, SupplierPriceListResponse
• Purchase Order: PurchaseOrderCreate, PurchaseOrderResponse
• Delivery: DeliveryCreate, DeliveryResponse
• Performance: PerformanceMetric, Alert, Scorecard

Key Hooks:

• Supplier (8 query hooks): useSuppliers, useSupplier, useSupplierStatistics, useActiveSuppliers, etc.
• Purchase Orders (2 query hooks): usePurchaseOrders, usePurchaseOrder
• Deliveries (2 query hooks): useDeliveries, useDelivery
• Performance (2 query hooks): useSupplierPerformanceMetrics, usePerformanceAlerts
• Mutations (12 hooks): CRUD operations for all entities

---

3. INVENTORY/PRODUCT API

File: /home/user/bakery_ia/frontend/src/api/types/inventory.ts Hooks: /home/user/bakery_ia/frontend/src/api/hooks/inventory.ts

Key Types:

• Ingredient: IngredientCreate, IngredientResponse
• Stock: StockCreate, StockResponse
• Stock Movement: StockMovementCreate, StockMovementResponse
• Transformation: ProductTransformationCreate, ProductTransformationResponse
• Food Safety: TemperatureLogResponse, FoodSafetyAlertResponse, FoodSafetyComplianceResponse
• Dashboard: InventoryDashboardSummary, InventoryAnalytics

Key Hooks:

• Ingredients (4 query hooks): useIngredients, useIngredient, useIngredientsByCategory, useLowStockIngredients
• Stock (6 query hooks): useStock, useStockByIngredient, useExpiringStock, useExpiredStock, useStockMovements, useStockAnalytics
• Transformations (5 query hooks): useTransformations, useTransformation, useTransformationSummary, etc.
• Mutations (13 hooks): CRUD + specialized operations like useStockOperations, useTransformationOperations

---

4. QUALITY TEMPLATE API

File: /home/user/bakery_ia/frontend/src/api/types/qualityTemplates.ts Hooks: /home/user/bakery_ia/frontend/src/api/hooks/qualityTemplates.ts

Key Types:

• QualityCheckTemplate, QualityCheckTemplateCreate, QualityCheckTemplateUpdate
• QualityCheckExecutionRequest, QualityCheckExecutionResponse
• ProcessStageQualityConfig, RecipeQualityConfiguration

Key Hooks:

• Query (5 hooks): useQualityTemplates, useQualityTemplate, useQualityTemplatesForStage, useQualityTemplatesForRecipe, useDefaultQualityTemplates
• Mutation (6 hooks): useCreateQualityTemplate, useUpdateQualityTemplate, useDeleteQualityTemplate, useDuplicateQualityTemplate, useExecuteQualityCheck, useValidateQualityTemplate

---

5. CUSTOMER ORDER API

File: /home/user/bakery_ia/frontend/src/api/types/orders.ts Hooks: /home/user/bakery_ia/frontend/src/api/hooks/orders.ts

Key Types:

• Customer: CustomerCreate, CustomerResponse
• Order: OrderCreate, OrderUpdate, OrderResponse
• OrderItem: OrderItemCreate, OrderItemResponse
• Dashboard: OrdersDashboardSummary
• Analytics: DemandRequirements, BusinessModelDetection

Key Hooks:

• Query (7 hooks): useOrders, useOrder, useCustomers, useCustomer, useOrdersDashboard, useDemandRequirements, useBusinessModelDetection
• Mutation (4 hooks): useCreateOrder, useUpdateOrderStatus, useCreateCustomer, useUpdateCustomer
• Utility (1 hook): useInvalidateOrders

---

CRITICAL MISALIGNMENTS IDENTIFIED

1. PAYMENT TERMS ENUM CONFLICT

Location: suppliers.ts vs orders.ts

Suppliers PaymentTerms:

• COD, NET_15, NET_30, NET_45, NET_60, PREPAID, CREDIT_TERMS

Orders PaymentTerms:

• IMMEDIATE, NET_30, NET_60

Impact: Two different enums with same name in different contexts could cause confusion and data inconsistency.

Recommendation: Unify these enums or clarify their separate domains.

---

2. DECIMAL VS NUMBER TYPE

Affected APIs: Suppliers, Orders

Issue: Backend uses Decimal for monetary values:

• supplier.credit_limit
• supplier.total_spent
• customer.total_spent
• customer.average_order_value

Frontend: Uses number type

Impact: Floating-point precision loss for currency calculations (e.g., $1.23 - $1.20 != $0.03)

Recommendation: Implement a Decimal wrapper type for all currency fields.

---

3. STOCK FIELD NAME INCONSISTENCY

Locations:

• StockCreate interface defines: unit_cost?: number
• useStockOperations hook uses: unit_price parameter

Impact: Potential API validation errors if hook sends wrong field name.

Recommendation: Audit backend to verify correct field name and update frontend accordingly.

---

4. PROCESS STAGE VS PRODUCTION STAGE CONFUSION

Quality Templates Define:

• MIXING, PROOFING, SHAPING, BAKING, COOLING, PACKAGING, FINISHING

Inventory Defines:

• RAW_INGREDIENT, PAR_BAKED, FULLY_BAKED, PREPARED_DOUGH, FROZEN_PRODUCT

Note: These are intentionally different (quality control vs production) - correctly separated but documentation needed.

---

5. RECORD<STRING, ANY> OVERUSE

Multiple type definitions use Record<string, any> for flexibility:

• instructions
• parameters
• thresholds
• scoring_criteria
• custom_requirements
• allergen_warnings

Risk: Loose typing defeats TypeScript's safety benefits.

Recommendation: Define specific interfaces for complex nested structures.

---

6. CREATED_BY FIELD HANDLING

Quality Templates: QualityCheckTemplateCreate requires created_by: string

Issue: Forms typically auto-fill from authenticated user context, not user input.

Recommendation: Verify API makes this optional or frontend passes authenticated user ID.

---

7. PRODUCT CLASSIFICATION

Location: inventory.ts - ProductSuggestionResponse, BatchClassificationResponse

Potential Issue: These suggest AI-based classification but exact API endpoints may differ from implementation.

Recommendation: Verify API contract matches suggestion response structure.

---

STATISTICS

Total TypeScript type definitions: 150+ Total React hooks: 80+ Total enums: 40+

By Domain:

• Recipes: 20 types, 10 hooks
• Suppliers: 35 types, 25 hooks
• Inventory: 25 types, 20 hooks
• Quality Templates: 12 types, 6 hooks
• Orders/Customers: 18 types, 7 hooks

---

KEY SERVICES LOCATION

All services are located in: /home/user/bakery_ia/frontend/src/api/services/

Main service files:

• recipes.ts
• suppliers.ts
• inventory.ts
• qualityTemplates.ts
• orders.ts
• procurement-service.ts
• purchase_orders.ts
• production.ts

---

RECOMMENDATIONS FOR CLEANUP

1. Priority 1 (Critical)

   • Unify PaymentTerms enums
   • Fix Decimal type handling for currencies
   • Verify stock field names (unit_cost vs unit_price)

2. Priority 2 (Important)

   • Replace Record<string, any> with specific types
   • Add validators matching backend
   • Document ProcessStage vs ProductionStage distinction

3. Priority 3 (Nice to Have)

   • Create shared enum definitions
   • Add JSDoc comments for all type fields
   • Implement Decimal wrapper for all monetary values
   • Create type guards for enum validation

---

FILES FOR FURTHER REVIEW

Backend schema files (for comparison):

• /home/user/bakery_ia/services/recipes/app/schemas/recipes.py
• /home/user/bakery_ia/services/orders/app/schemas/order_schemas.py
• /home/user/bakery_ia/services/production/app/schemas/quality_templates.py
• /home/user/bakery_ia/services/suppliers/app/schemas/suppliers.py
• /home/user/bakery_ia/services/suppliers/app/schemas/performance.py
• /home/user/bakery_ia/services/inventory/app/schemas/inventory.py