From 0343bf022e58316869309556ec2fe81b1354808e Mon Sep 17 00:00:00 2001 From: Dariusz L Date: Sun, 2 Aug 2026 22:19:38 +0200 Subject: [PATCH] docs: document provider availability states --- docs/architecture.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index a58a8ba..6c31b50 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -43,6 +43,48 @@ the responsibility and add a focused test in `tests/test_workflow_components.py` or `tests/test_workflow_analyzer.py`. Keep imports within the documented layer direction; `tests/test_workflow_boundaries.py` enforces this contract. +## Search provider availability + +Search responses distinguish an unavailable provider from a successful search +with no matching model. Provider-specific failures are exposed in +`source_status` while the older `source_errors` field remains available for +diagnostics and compatibility: + +```json +{ + "source_errors": { + "civarchive": "CivArchive search failed: HTTP 522" + }, + "source_status": { + "civarchive": { + "state": "unavailable", + "code": "provider_unavailable", + "retryable": true, + "http_status": 522, + "message": "CivArchive may be overloaded or temporarily unavailable. Please try again." + } + } +} +``` + +The frontend uses `source_status` for user-facing labels and notifications: + +- `state: unavailable` means the provider or its network path is temporarily + unavailable; it is not a confirmed no-match result. +- `state: rate_limited` means the provider asked the client to slow down. +- `state: not_found` means the provider did not expose a matching page. +- `state: error` represents a non-retryable provider rejection or another + provider-specific failure. + +When `retryable` is true, the source status row shows a retry action. A retry +repeats only that provider with a forced refresh and does not rerun the other +search sources. Automatic retry is intentionally not performed, so a slow or +overloaded provider cannot delay every search attempt. + +The backend log uses structured fields such as `code`, `http_status`, +`retryable`, and `error_type`; user-facing messages should come from the safe +`message` field rather than the raw exception text. + ## Frontend architecture The frontend keeps ComfyUI-specific integration at the extension boundary in