Synchronization

The Data sync administration page (/admin/jobs) manages shared catalog, price and image jobs. UI-triggered jobs are queued for the background worker.

Job kinds

Kind	Work	Default interval
catalog	Import game sets, cards, printings, names; supplemental sources and comparisons	168 hours
prices	Update market snapshots where the game has sources	24 hours
images	Cache card images, normally owned printings, plus provider-specific broader coverage	24 hours
refresh	Re-fetch stale/incomplete individual cards where supported	48 hours

Catalog sync can also store quotes supplied with card data. Price jobs do not replace catalog imports. An image job cannot invent an image URL missing from all sources.

Manual runs and statuses

Select a game and a job kind. The API responds with a run ID and HTTP 202; the worker checks the manual queue every three seconds. A busy worker or external source can delay completion.

Status	Meaning
queued	Waiting for the worker
running	A process owns the run
success	Run completed; read the counters for partial source/image outcomes
failed	Error recorded; inspect logs
cancelled	Deliberately stopped, for example when a manual run takes over

A manual run can take over a running automatic run of the same game and kind. Conflicting duplicate work can return 409. There is no guarantee that every requested sync starts instantly.

Reports include counters such as cards, sets, printings, prices received, stored/cached/refused images, missing data, source differences and refreshed cards. A successful job with missing images is not equivalent to complete image coverage.

Schedules

The schedule supports intervals, daily times, selected weekdays and monthly dates in an IANA time zone such as Europe/Paris. Monthly dates are restricted to 1–28. Fixed times use HH:MM and support up to 24 distinct times. Weekdays use Monday=0 through Sunday=6 in API requests.

Schedules saved through the UI are persisted in app_setting and override the environment defaults. Resetting the schedule restores those defaults. Fixed-time previews do not save changes; times before a newly saved schedule are not retrospectively caught up for already initialized jobs. Never-initialized or version-outdated jobs can still run immediately.

The automatic scheduler checks on a one-minute cycle around its work; long sequential imports can delay later jobs. Failed automatic attempts are retried after at least an hour. Manual runs do not replace or delay the normal automatic-run schedule. A provider catalog-version change after an upgrade can force an earlier catalog refresh; updated catalogs can make image work due again.

Limit worker games

TCG_WORKER_GAMES=[] means all installed games. A selected list limits automatic work. For backward compatibility, pokemon alone expands to all Pokémon markets; yugioh alone expands to TCG and OCG. To choose only the international/TCG member using this setting, account for that family expansion rather than assuming the base ID is always a single catalog selector.

Catalog visibility in user settings is independent of worker selection.

Automatic maintenance

When a catalog refresh causes the median measured API latency over 20 seconds to exceed the configured threshold (default 500 ms), users may receive HTTP 503 and a maintenance page. Administrators keep access. The load monitor requires sufficiently fast responses for 30 seconds to end that state.

This is load-triggered, not a maintenance page shown during every sync. The health endpoint reports its state. Set TCG_MAINTENANCE_ENABLED and TCG_MAINTENANCE_LATENCY_MS according to the deployment, and diagnose capacity before disabling the behavior.

CLI jobs

docker compose exec api zukan sync mtg --kind catalog
docker compose exec api zukan sync mtg --kind prices
docker compose exec api zukan sync mtg --kind images
docker compose exec api zukan sync mtg --kind refresh

CLI jobs run in the invoked process, unlike the UI queue. Use them deliberately when no equivalent job is active.

Reset a catalog

Reset removes catalog data except printings protected by collection references, then queues a catalog import. It refuses while that game has queued/running work. It is a maintenance action, not a routine first response to one missing image. Back up before broad catalog repair; retained inventory does not mean all catalog metadata/history is retained.

Implementation references

• backend/app/worker.py
• backend/app/services/schedule.py
• backend/app/services/jobs.py
• backend/app/api/admin.py