Classification Workflow Step

[FeezyHendrix]

What type of PR is this? (check all applicable)

• 🍕 Feature
• 🐛 Bug Fix
• 📝 Documentation
• 🧑‍💻 Refactor
• ✅ Test
• 🤖 Build or CI
• ❓ Other (please specify)

Related Issue

Related to image classification workflow enhancement

Describe this PR

This PR implements several critical fixes and enhancements to the drone image classification workflow:

Key Changes:

1. Fixed Async S3 Operations: Implemented proper async handling for MinIO S3 operations using run_in_threadpool to prevent blocking the event loop during image downloads in the classification process.

2. ARQ Worker Connectivity: Added extra_hosts configuration to the ARQ worker in docker-compose.yaml to enable MinIO connectivity via localhost, which is required for generating presigned URLs accessible from the browser.

3. Database Schema Fixes: Updated create_project_image function to include batch_id and rejection_reason fields in both INSERT statements and RETURNING clauses, resolving Pydantic validation errors.

4. Classification Status Flow: Changed classification workflow to work with STAGED status instead of UPLOADED status, aligning with the actual upload flow where images are initially staged in user-uploads directory.

5. Frontend API Corrections: Updated frontend to send batch_id as query parameter instead of request body to match backend endpoint expectations.

6. Button State Management:

   • Disabled "Next" button on Image Upload step until files are successfully uploaded
   • Disabled "Start Classification" button when no staged images are available for classification

7. Toast Notification Fix: Prevented duplicate success notifications by implementing a ref-based flag to ensure only one notification shows per upload batch.

8. EXIF Processing: Temporarily disabled frontend EXIF extraction (commented out) as the backend handles this during the process_uploaded_image ARQ task.

9. Consistent Return Values: Fixed classify_batch function to always return complete result dictionaries with all expected keys, preventing KeyError exceptions.

Technical Details:

Backend Changes:

• src/backend/app/s3.py: Added run_in_threadpool wrapper for async S3 operations
• src/backend/app/images/image_logic.py: Updated INSERT/RETURNING clauses to include batch_id and rejection_reason
• src/backend/app/projects/classification_routes.py: Changed to query for staged status, added staged count to status response, added pre-flight image count check
• src/backend/app/projects/image_classification.py: Updated classify_batch to query STAGED images and return consistent result structure
• compose.yaml: Added extra_hosts for ARQ worker

Frontend Changes:

• src/frontend/src/services/classification.ts: Changed to send batch_id as query parameter
• src/frontend/src/api/projects.ts: Added proper TypeScript typing for BatchStatusSummary
• src/frontend/src/components/.../ImageClassification.tsx: Changed button disable logic to check for staged count
• src/frontend/src/components/.../DroneImageProcessingWorkflow/index.tsx: Added Next button disable logic based on batch_id presence
• src/frontend/src/components/.../UppyFileUploader/index.tsx: Fixed duplicate toast notifications, commented out EXIF extraction

Screenshots

Screenshots would show:

• Disabled "Next" button before file upload
• Enabled "Next" button after successful upload
• Disabled "Start Classification" button when no staged images
• Single success toast notification after batch upload completes

Alternative Approaches Considered

1. Status Flow: Considered using UPLOADED status for classification but determined STAGED is more appropriate for the current workflow where images remain in staging directory.

2. Batch ID Persistence: Explored adding an endpoint to retrieve the latest batch_id from backend vs. maintaining state in frontend component.

3. S3 Connectivity: Initially attempted to change S3_ENDPOINT configuration, but used extra_hosts instead to maintain backward compatibility with presigned URLs.

Review Guide

Testing the Changes:

1. Upload Flow:

   • Open Drone Image Processing Workflow modal
   • Verify "Next" button is disabled on step 1
   • Upload drone images
   • Verify single success notification appears
   • Verify "Next" button becomes enabled
   • Verify automatic progression to Classification step

2. Classification Flow:

   • On Classification step, verify status summary shows correct counts (Staged, Total, etc.)
   • Verify "Start Classification" button is disabled if no staged images
   • Click "Start Classification" button
   • Verify ARQ worker processes images successfully (check logs)
   • Verify images are classified and status updates in real-time

3. ARQ Worker:

   • Check ARQ worker logs for successful MinIO connections
   • Verify no connection refused errors to localhost:9000
   • Verify images are processed and saved with correct batch_id

4. Backend Endpoints:

   • Test /api/projects/{project_id}/classify-batch/?batch_id={batch_id} endpoint
   • Test /api/projects/{project_id}/batch/{batch_id}/status/ returns staged count
   • Verify batch classification only starts when staged images exist

Checklist before requesting a review

• 📖 Read the HOT Code of Conduct: https://docs.hotosm.org/code-of-conduct
• 👷‍♀️ Create small PRs. In most cases, this will be possible.
• ✅ Provide tests for your changes.
• 📝 Use descriptive commit messages.
• 📗 Update any related documentation and include any relevant screenshots.

[optional] What gif best describes this PR or how it makes you feel?

---

Note: This PR includes multiple related fixes that were discovered and resolved during the implementation of the image classification workflow. Each change addresses a specific issue that was blocking the classification functionality.

[spwoodcock]

Nice! I'm sure this is going to be great 😄

I'll try my best to review this as soon as I can - got quite a few things on.

Couple pieces of feedback though:

• Please try and make a draft PR as early as possible, so this can be reviewed incrementally in future. It's a huge task to do an in-depth review of thousands of lines of code & maintainer availability often rises and falls.
• If possible, it's great regularly rebasing on the target branch, meaning conflicts are addressed bit-by-bit, as they happen & the final code is always in sync.

Thank you! 🙏

[spwoodcock]

Oh also, thanks so much for the great detailed description - really helps!

[spwoodcock]

This is looking great! But perhaps we should be targeting a merge to dev instead of the image-workflow-integration branch? Or perhaps we can just update image-workflow-integration to be in sync to dev to ensure we don't have merge conflicts on the final merge.

I'll let you take a look at the merge conflict resolution & come back for a second review 👍

[spwoodcock]

Does this install correctly and run well in docker by the way? I haven't tested, but my assumption is that OpenCV may require some additional dev packages / headers to install and run, but I'm not certain on that. Please confirm it's working well in docker 🙏

[FeezyHendrix]

It's working correctly as of now, cause I run the application through docker, I can't guarantee the behaviour is prod.

[spwoodcock]

This looks pretty clean and nice - good job 😄

We should give it a thorough test. Can we deploy the branch to dev, instead of merging into image-workflow-integration and see all of these new workflows in action? 🙏

[spwoodcock]

Small thing, there is a pre-commit error about an bare except.

Please update to the actual exception type at best, else except Exception as e at worst

[spwoodcock]

Minor feedback:

• It's good that the polling interval isn't too aggressive, but should we consider some kind of user feedback while they are waiting for number to change? I think the most obvious is to add a loading spinner in space of the 0 values, to show those stages haven't started yet (but to indicate that they will). Open to other options 👍
• We probably have a few too many stages to display to the user. It's perfect for us, and perhaps even to power users via an 'advanced' toggle or something, but to most general users I think we should remove a few stages:
  • Staged and Ready could be combined into simply 'Uploaded'?
  • The total on the left is a bit confusing, as it's not distinct from other stages - it seems like a separate stage. I'm thinking we could possibly remove the total from this part entirely (the user can get a rough idea by counting the numbers across stages)
  • Assigned should be worded as 'Complete'
  • Rejected, Unmatched, Invalid EXIF can all be bundled into an 'Issues' category. This could be computed on the frontend, rather than changing the API.
  • Keep 'Duplicates' as this is useful.
  • The API response can remaining the same, as the more details categories are useful to developers and other users - they could be accessed in other ways in future

[spwoodcock]

Now #678 has been merged, this PR needs to probably be rebased on dev.

I think the commits in the merged PR were squashed when the branch was made, but personally I would have kept the history.
This branch may have updated without conflict if the commit hashes were matching.

Either way, we need to make sure only to include the relevant files changes for this PR here 😄