fix(backend): enforce single-worker deployment for in-memory job tracking

Model-download and global-reclustering job state lives in per-worker memory, so
running multiple workers would let a job start in one worker while status polls
hit another (404s, duplicate jobs). Hardcode the server to a single worker in
run.sh and run-server.ps1 (removing the WORKERS override) and document the
constraint at the in-memory state. Replaces the previous best-effort startup
warning, which could not observe the real worker count.

Author: VanshajPoonia

backend/main.py

@@ -64,23 +64,11 @@ async def lifespan(app: FastAPI):
     db_create_albums_table()
     db_create_album_images_table()
     db_create_metadata_table()
-    # Model-download and global-reclustering job tracking is in-memory and
-    # per-worker. With more than one worker, a job started in one worker is
-    # invisible to the others, so status polls can miss it and duplicate jobs
-    # can start. Warn loudly so deployments keep a single worker (WORKERS=1).
-    try:
-        worker_count = int(os.environ.get("WORKERS", "1"))
-    except ValueError:
-        worker_count = 1
-    if worker_count > 1:
-        logger.warning(
-            "WORKERS=%s: model-download and global-reclustering job tracking is "
-            "in-memory and per-worker. Run with a single worker (WORKERS=1) to "
-            "avoid duplicate jobs and missed status polls.",
-            worker_count,
-        )
-
     # Create ProcessPoolExecutor and attach it to app.state
+    # NOTE: model-download and global-reclustering job tracking is in-memory and
+    # per-worker, so the server is launched with a single worker (see run.sh /
+    # run-server.ps1). Keep it that way unless that state is moved to a shared
+    # store.
     app.state.executor = ProcessPoolExecutor(max_workers=1)
 
     # Start the SSE model download cleanup task

backend/run-server.ps1

@@ -44,13 +44,14 @@ if ($args[0] -eq "--test") {
         Start-Sleep -Seconds 3
     }
 } else {
-    # Get the WORKERS environment variable or use a default value
-    $workers = if ($env:WORKERS) { $env:WORKERS } else { "1" }
-    Write-Host "WORKERS: $workers"
+    # Model-download and global-reclustering job tracking is in-memory and
+    # per-worker, so the server must run with a single worker; a job started in
+    # one worker would be invisible to others (missed status polls, duplicate
+    # jobs). Do not raise the worker count above 1.
 
     # Start the Hypercorn server
     $process = Start-Process -FilePath "hypercorn" `
-                             -ArgumentList "main:app --workers $workers --bind 0.0.0.0:8000" `
+                             -ArgumentList "main:app --workers 1 --bind 0.0.0.0:8000" `
                              -PassThru
 
     # Wait for process termination or Ctrl+C

backend/run.sh

@@ -21,7 +21,9 @@ if [[ $1 == "--test" ]]; then
         sleep 3
     done
 else
-    # print the value of the WORKERS environment variable
-    echo "WORKERS: ${WORKERS:-1}"
-    hypercorn main:app --workers ${WORKERS:-1} --bind 0.0.0.0:8000
+    # Model-download and global-reclustering job tracking is in-memory and
+    # per-worker, so the server must run with a single worker; a job started in
+    # one worker would be invisible to others (missed status polls, duplicate
+    # jobs). Do not raise the worker count above 1.
+    hypercorn main:app --workers 1 --bind 0.0.0.0:8000
 fi