Technology
How Runners Photos runs your tagging jobs under the hood.
Short story
Runners Photos splits the work into two layers. Your browser mostly starts jobs, shows progress, and sends small requests in sequence. Most of the processing happens on our servers: they talk to SmugMug, pull images in batches, run automated AI image analysis on photos that need fresh reads (to detect bib numbers and related cues), optionally match results across images, then write keywords back. That pipeline is limited by network round-trips, external APIs, and analysis time, not by how fast the page redraws.
You can use that pipeline in two ways:
- Client-side processing: Your page drives the job. After each batch finishes, the browser requests the next; progress updates as each batch returns (no polling), and you can stop by simply not requesting the next batch. The job stays active only while that request loop is running in your tab.
- Server-side background: You start a job and our worker advances the same stages (including scan, image analysis where needed, match, and write) without your browser open. You see progress by polling or when you return to the page; you can cancel the job, and the worker honors it between batches. Same heavy lifting; the difference is who advances the work and how you see updates.
So client-side versus background is about who advances the work and how you see progress: in lockstep with each batch in the client, or on a schedule (polling) and when you return in the background. The slow part is always the server-side pipeline.
Long story: architecture
What runs where
The expensive steps run on our servers: authenticating your session, calling SmugMug, downloading or preparing images, running AI-based image analysis on each image that the scan phase needs to evaluate, reconciling results where we match across photos, and PATCHing keywords. The client is an orchestrator and display, quick to update, but not where the heavy I/O or inference happens.
Scanning and image analysis
A job typically scans the album in batches: the server fetches image metadata and, when needed, the image itself. For images that require a fresh read from the photo, we analyze the image with automated vision models to infer bib numbers (and related signals). That step happens after the image is in play for that batch, before or alongside accumulating results that later feed matching and writing. Total time grows with how many images go through that path and how large each batch is.
Why server time dominates
Each batch can include multiple SmugMug calls, preparation work, model inference (the image-analysis step), and writes. Those add up in wall-clock time. The UI feels fast because it only reflects completed batches; the gap between updates is the server finishing that chunk of work.
Batching and APIs
We process in batches to respect API limits, control load, and keep failures bounded. More images mean more batches and longer end-to-end time, whether you use client-side or background mode.
Client-side processing
Your browser sends a request; the server runs a slice of the pipeline (including scan and image analysis for that slice where applicable); the response updates progress and the log. The client then requests the next slice. You are in lockstep with the server: progress updates as each batch returns, and you can stop mid-job by cancelling (no further requests). The page must stay in that loop for the job to continue.
Server-side background
After you start a background job, a worker pulls work from our queue and runs the same pipeline; your open page does not request each batch. You see progress by polling (or when you return) and can cancel the job; the worker checks for cancel between batches. Same pipeline and capabilities; background means decoupled from your browser and updated on a schedule rather than as each batch returns. There is still queue and scheduling overhead—background is not instant.
Choosing a mode
Client-side processing fits when you want progress to update as each batch completes (no polling), to cancel with the page in the loop, or to process a smaller album without leaving the tab. Progress and cancel feel immediate because your page is the one requesting each batch.
Server-side background fits large albums or when you do not want to keep the page open; you can still watch progress (via polling or when you return) and cancel the job. Work continues on our side while you check back for status or logs.
Under both modes, the heavy work is the same: SmugMug access, AI image analysis where the scan needs it, matching, and keyword writes.
Summary
The browser coordinates; the server does SmugMug, AI image analysis on photos after they are pulled into the scan, matching, and keyword writes. Client-side means your page drives each batch; background means our worker does. Latency comes from APIs, batching, and vision-based analysis per image, not from how fast the client redraws.
Note. Details of how we batch, analyze, and schedule work are subject to change as we improve performance, reliability, and cost. The ideas above describe the architecture in principle, not a fixed contract.