thrilltrack-explorer/docs/logging/SUBMISSION_FLOW_LOGGING.md

# Submission Flow Logging

This document describes the structured logging implemented for tracking submission data through the moderation pipeline.

## Overview

The submission flow has structured logging at each critical stage to enable debugging and auditing of data transformations.

## Logging Stages

### 1. Edit Stage
**Location**: `src/lib/submissionItemsService.ts` → `updateSubmissionItem()`

**Log Points**:
- Update item start (when moderator edits)
- Saving park data (before database write)
- Park data saved successfully (after database write)

**Log Format**:
```typescript
console.info('[Submission Flow] Update item start', {
  itemId: string,
  hasItemData: boolean,
  statusUpdate: string | undefined,
  timestamp: ISO string
});

console.info('[Submission Flow] Saving park data', {
  itemId: string,
  parkSubmissionId: string,
  hasLocation: boolean,
  locationData: object | null,
  fields: string[],
  timestamp: ISO string
});
```

### 2. Validation Stage
**Location**: `src/hooks/moderation/useModerationActions.ts` → `handleApproveSubmission()`

**Log Points**:
- Preparing items for validation (after fetching from DB)
- Transformed park data (after temp_location_data → location transform)
- Starting validation (before schema validation)
- Validation completed (after schema validation)
- Validation found blocking errors (if errors exist)

**Log Format**:
```typescript
console.info('[Submission Flow] Transformed park data for validation', {
  itemId: string,
  hasLocation: boolean,
  locationData: object | null,
  transformedHasLocation: boolean,
  timestamp: ISO string
});

console.warn('[Submission Flow] Validation found blocking errors', {
  submissionId: string,
  itemsWithErrors: Array<{
    itemId: string,
    itemType: string,
    errors: string[]
  }>,
  timestamp: ISO string
});
```

### 3. Approval Stage
**Location**: `src/lib/submissionItemsService.ts` → `approveSubmissionItems()`

**Log Points**:
- Approval process started (beginning of batch approval)
- Processing item for approval (for each item)
- Entity created successfully (after entity creation)

**Log Format**:
```typescript
console.info('[Submission Flow] Approval process started', {
  itemCount: number,
  itemIds: string[],
  itemTypes: string[],
  userId: string,
  timestamp: ISO string
});

console.info('[Submission Flow] Processing item for approval', {
  itemId: string,
  itemType: string,
  isEdit: boolean,
  hasLocation: boolean,
  locationData: object | null,
  timestamp: ISO string
});
```

## Key Data Transformations Logged

### Park Location Data
The most critical transformation logged is the park location data flow:

1. **Database Storage**: `temp_location_data` (JSONB in park_submissions)
2. **Display/Edit**: `location` (transformed for form compatibility)
3. **Validation**: `location` (transformed from temp_location_data)
4. **Save**: `temp_location_data` (transformed back for storage)
5. **Approval**: `location` (transformed from temp_location_data)

**Why this matters**: Location validation errors typically indicate a break in this transformation chain.

## Debugging Workflow

### To debug location validation errors:

1. **Check browser console** for `[Submission Flow]` logs
2. **Verify data at each stage**:
   ```javascript
   // Edit stage - should show temp_location_data being saved
   [Submission Flow] Saving park data { hasLocation: true, locationData: {...} }
   
   // Validation stage - should show location after transformation
   [Submission Flow] Transformed park data { hasLocation: true, transformedHasLocation: true }
   
   // Approval stage - should show location present
   [Submission Flow] Processing item { hasLocation: true, locationData: {...} }
   ```

3. **Look for missing data**:
   - If `hasLocation: false` in "Saving park data" → Edit form didn't capture location
   - If `hasLocation: true` but `transformedHasLocation: false` → Transformation failed
   - If validation logs missing → Check database query/fetch

## Error Logging Integration

Structured errors use the `handleError()` utility from `@/lib/errorHandler`:

```typescript
handleError(error, {
  action: 'Update Park Submission Data',
  metadata: { 
    itemId, 
    parkSubmissionId,
    updateFields: Object.keys(updateData)
  }
});
```

Errors are logged to:
- **Database**: `request_metadata` table
- **Admin Panel**: `/admin/error-monitoring`
- **Console**: Browser developer tools (with reference ID)

## Log Filtering

To filter logs in browser console:
```javascript
// All submission flow logs
localStorage.setItem('logFilter', 'Submission Flow');

// Specific stages
localStorage.setItem('logFilter', 'Validation');
localStorage.setItem('logFilter', 'Saving park data');
```

## Performance Considerations

- Logs use `console.info()` and `console.warn()` which are stripped in production builds
- Sensitive data (passwords, tokens) are never logged
- Object logging uses shallow copies to avoid memory leaks
- Timestamps use ISO format for timezone-aware debugging

## Future Enhancements

- [ ] Add edge function logging for backend approval process
- [ ] Add real-time log streaming to admin dashboard
- [ ] Add log retention policies (30-day automatic cleanup)
- [ ] Add performance metrics (time between stages)
- [ ] Add user action correlation (who edited what when)