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:

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:

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:

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:

   // 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:

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:

// 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)