I Added a Queued Video Text Overlay Workflow to Reel Quick

Project repo: ronin1770/reel-quick

I recently worked on a backend improvement in Reel Quick that solved a practical workflow problem around text overlays on videos.

Instead of coupling overlay editing directly with processing, I moved the feature to a two-step queued workflow.

What I changed

I introduced two separate backend actions:

• POST /videos/{video_id}/text-overlays
  
  Saves or merges text overlay items for a video.

• POST /enqueue/text-overlay
  
  Queues processing only when the user is actually ready.

Why I changed it

The old approach risked a few common problems:

• processing could start before all overlays were finalized
• repeated edits could create duplicate overlay records
• there was no clean way to track queued, running, completed, or failed jobs

By separating save from process, the flow became more reliable for users and much easier to reason about on the backend.

Key implementation decisions

A few details mattered here:

• multiple overlays can be saved for a single video
• duplicate overlay saves are deduped by overlay_id
• enqueue accepts only video_id
• the backend resolves the input path from the stored video record
• processing requires the source video to already be completed
• a separate text_overlay_jobs collection tracks async job state

Why this pattern works

I like this design because it reflects how users actually work.

They want to:

1. add and tweak overlays
2. save changes while editing
3. click process only when everything is ready

That sounds simple, but it makes a big difference in reliability.

Repo

Project repo: ronin1770/reel-quick

Final thought

This was a useful reminder that not every feature should be handled in one request-response cycle.

Sometimes the better design is to let users build state first, then explicitly enqueue background processing when they’re done.