Decouple File Upload from Audio Analysis in /analyze Endpoint

[sorochak]

Currently, the /analyze endpoint handles both file upload and BirdNET audio analysis in a single step. This issue proposes separating those concerns into two endpoints: one for file upload and one for analysis.

Motivation

• Improve modularity and separation of concerns
• Support future enhancements like:
  • Queuing analysis jobs for background processing
• Make the system more scalable, testable, and maintainable

Proposed Changes

• Create a new POST /upload endpoint:

  • Validates file type (.wav or .zip)
  • Stores the file (e.g., local filesystem or S3)
  • Returns a file_id or file path for later reference

• Update POST /analyze endpoint:

  • Accepts a file_id or file path
  • Loads the file from storage
  • Runs BirdNET analysis and returns results

Example Flow

1. POST /upload → returns { "file_id": "abc123.wav" }
2. POST /analyze with payload { "file_id": "abc123.wav" } → returns analysis results

Benefits

• Enables analysis reuse without re-uploading
• Makes it easier to support asynchronous/background tasks
• Future-proof design for large-scale or multi-user systems
• Cleaner code and route logic