# Modular Request Flow Architecture - Implementation Summary

## Overview

This document summarizes the implementation of a modular, plug-and-play architecture for handling different request flow types (CUSTOM and DEALER_CLAIM) in the application.

## What Was Implemented

### 1. Request Type Detection Utilities (`src/utils/requestTypeUtils.ts`)

Created centralized utilities for detecting and handling different request types:

- `isCustomRequest(request)` - Checks if a request is a custom request
- `isDealerClaimRequest(request)` - Checks if a request is a dealer claim request
- `getRequestFlowType(request)` - Returns the flow type ('CUSTOM' | 'DEALER_CLAIM')
- `getRequestDetailRoute(requestId, request?)` - Gets the appropriate route for request detail
- `getCreateRequestRoute(flowType)` - Gets the route for creating a new request

### 2. Global Navigation Utility (`src/utils/requestNavigation.ts`)

Created a single point of navigation logic for all request-related routes:

- `navigateToRequest(options)` - Main navigation function that handles:
  - Draft requests (routes to edit)
  - Different flow types
  - Status-based routing
- `navigateToCreateRequest(navigate, flowType)` - Navigate to create request based on flow type
- `createRequestNavigationHandler(navigate)` - Factory function for creating navigation handlers

### 3. Modular Flow Structure (`src/flows/`)

Created a modular folder structure for different request flows:

```
src/flows/
├── custom/
│   └── index.ts          # Exports Custom flow components
├── dealer-claim/
│   └── index.ts          # Exports Dealer Claim flow components
├── shared/
│   └── components/       # Shared components (for future use)
└── index.ts              # Flow registry and utilities
```

**Flow Registry** (`src/flows/index.ts`):
- `FlowRegistry` - Maps flow types to their modules
- `getFlowModule(flowType)` - Gets the flow module for a type
- `getOverviewTab(flowType)` - Gets the appropriate overview tab component
- `getWorkflowTab(flowType)` - Gets the appropriate workflow tab component

### 4. Updated RequestDetail Component

Modified `src/pages/RequestDetail/RequestDetail.tsx` to:
- Use flow type detection instead of hardcoded checks
- Dynamically load appropriate components based on flow type
- Support plug-and-play architecture for different flows

**Key Changes**:
- Replaced `isClaimManagementRequest()` with `getRequestFlowType()`
- Uses `getOverviewTab()` and `getWorkflowTab()` to get flow-specific components
- Maintains backward compatibility with existing components

### 5. Updated Navigation Throughout App

Updated all request card click handlers to use the global navigation utility:

**Files Updated**:
- `src/App.tsx` - Main `handleViewRequest` function
- `src/pages/ApproverPerformance/components/ApproverPerformanceRequestList.tsx`
- `src/pages/DetailedReports/DetailedReports.tsx`

All navigation now goes through `navigateToRequest()` for consistency.

## How to Use

### For Developers

### 1. Navigating to a Request

```typescript
import { navigateToRequest } from '@/utils/requestNavigation';

// In a component with navigate function
navigateToRequest({
  requestId: 'REQ-123',
  requestTitle: 'My Request',
  status: 'pending',
  request: requestObject, // Optional: helps determine flow type
  navigate: navigate,
});
```

### 2. Getting Flow-Specific Components

```typescript
import { getOverviewTab, getWorkflowTab } from '@/flows';
import { getRequestFlowType } from '@/utils/requestTypeUtils';

const flowType = getRequestFlowType(request);
const OverviewTab = getOverviewTab(flowType);
const WorkflowTab = getWorkflowTab(flowType);

// Use in JSX
<OverviewTab {...props} />
<WorkflowTab {...props} />
```

### 3. Detecting Request Type

```typescript
import { 
  getRequestFlowType, 
  isCustomRequest, 
  isDealerClaimRequest 
} from '@/utils/requestTypeUtils';

// Check specific type
if (isDealerClaimRequest(request)) {
  // Handle dealer claim specific logic
}

// Get flow type
const flowType = getRequestFlowType(request); // 'CUSTOM' | 'DEALER_CLAIM'
```

## Adding a New Flow Type

To add a new flow type (e.g., "VENDOR_PAYMENT"):

### Step 1: Update Type Definitions

```typescript
// src/utils/requestTypeUtils.ts
export type RequestFlowType = 'CUSTOM' | 'DEALER_CLAIM' | 'VENDOR_PAYMENT';

export function isVendorPaymentRequest(request: any): boolean {
  // Add detection logic
  return request.workflowType === 'VENDOR_PAYMENT';
}

export function getRequestFlowType(request: any): RequestFlowType {
  if (isVendorPaymentRequest(request)) return 'VENDOR_PAYMENT';
  if (isDealerClaimRequest(request)) return 'DEALER_CLAIM';
  return 'CUSTOM';
}
```

### Step 2: Create Flow Folder

```
src/flows/vendor-payment/
└── index.ts
```

```typescript
// src/flows/vendor-payment/index.ts
export { VendorPaymentOverviewTab } from '@/pages/RequestDetail/components/tabs/VendorPaymentOverviewTab';
export { VendorPaymentWorkflowTab } from '@/pages/RequestDetail/components/tabs/VendorPaymentWorkflowTab';
```

### Step 3: Update Flow Registry

```typescript
// src/flows/index.ts
import * as VendorPaymentFlow from './vendor-payment';

export const FlowRegistry = {
  CUSTOM: CustomFlow,
  DEALER_CLAIM: DealerClaimFlow,
  VENDOR_PAYMENT: VendorPaymentFlow,
} as const;

export function getOverviewTab(flowType: RequestFlowType) {
  switch (flowType) {
    case 'VENDOR_PAYMENT':
      return VendorPaymentFlow.VendorPaymentOverviewTab;
    // ... existing cases
  }
}
```

### Step 4: Create Components

Create the flow-specific components in `src/pages/RequestDetail/components/tabs/`:
- `VendorPaymentOverviewTab.tsx`
- `VendorPaymentWorkflowTab.tsx`

## Benefits

1. **Modularity**: Each flow type is isolated in its own folder
2. **Maintainability**: Changes to one flow don't affect others
3. **Scalability**: Easy to add new flow types
4. **Consistency**: Single navigation utility ensures consistent routing
5. **Type Safety**: TypeScript ensures correct usage
6. **Reusability**: Shared components can be used across flows

## Migration Notes

### Backward Compatibility

- All existing code continues to work
- `isClaimManagementRequest()` still works (now uses `isDealerClaimRequest()` internally)
- Existing components are preserved and work as before

### Breaking Changes

None. This is a non-breaking enhancement.

## Testing

To test the new architecture:

1. **Test Custom Requests**:
   - Create a custom request
   - Navigate to its detail page
   - Verify correct components are loaded

2. **Test Dealer Claim Requests**:
   - Create a dealer claim request
   - Navigate to its detail page
   - Verify dealer claim-specific components are loaded

3. **Test Navigation**:
   - Click request cards from various pages
   - Verify navigation works correctly
   - Test draft requests (should route to edit)

## Future Enhancements

- [ ] Add flow-specific validation rules
- [ ] Add flow-specific API endpoints
- [ ] Add flow-specific permissions
- [ ] Add flow-specific analytics
- [ ] Add flow-specific notifications
- [ ] Create shared request card component
- [ ] Add flow-specific creation wizards

## Files Created

1. `src/utils/requestTypeUtils.ts` - Request type detection utilities
2. `src/utils/requestNavigation.ts` - Global navigation utility
3. `src/flows/custom/index.ts` - Custom flow exports
4. `src/flows/dealer-claim/index.ts` - Dealer claim flow exports
5. `src/flows/index.ts` - Flow registry
6. `src/flows/shared/components/index.ts` - Shared components placeholder
7. `src/flows/README.md` - Flow architecture documentation

## Files Modified

1. `src/pages/RequestDetail/RequestDetail.tsx` - Uses flow registry
2. `src/App.tsx` - Uses navigation utility
3. `src/pages/ApproverPerformance/components/ApproverPerformanceRequestList.tsx` - Uses navigation utility
4. `src/pages/DetailedReports/DetailedReports.tsx` - Uses navigation utility

## Conclusion

The modular architecture is now in place and ready for use. The system supports plug-and-play flow types, making it easy to add new request types in the future while maintaining clean separation of concerns.