docs/ADR.md

# Architecture Decision Records — NeoFix-API (SozoFix backend)

This log records the "why" behind non-obvious backend decisions so future sessions
keep continuity. Append new records at the bottom. Newest decisions supersede older
ones only when explicitly marked. Status: Accepted | Superseded | Deprecated.

Stack recap: single-file Flask (`main.py`) on a Hugging Face Space (git remote is the
Space itself; pushing `main` redeploys). Firebase Realtime DB + Storage via Admin SDK.
Google GenAI (Gemini) for text/image, Deepgram for TTS, Stripe, Resend.

---

## ADR-001 — Asynchronous background generation for repair guides
**Date:** 2026-07-04 · **Status:** Accepted

**Context.** `PUT /api/projects/<id>/approve` was one synchronous Gemini call asking for
5 steps with interleaved images, then uploads + TTS, all inside the request. Two failures:
(1) the newer image model returns fewer inline images than text steps, and the old code
truncated steps to `min(steps, images)`, so users got fewer than 5 steps; (2) the whole
job risked the Hugging Face Space HTTP timeout (~60 to 90s). The frontend meanwhile showed
a fake client-side progress bar that hit 100% regardless of backend state.

**Decision.** Split validation from work. `/approve` now validates (auth, credits, ownership,
re-entrancy guard), sets project `status=generating`, seeds a `projects/{id}/generationProgress`
node, spawns a `threading.Thread(daemon=True)` running `_run_guide_generation`, and returns
**202** immediately. A new lightweight `GET /api/projects/<id>/progress` is polled by the client.
A staleness guard in that endpoint flips a stuck `generating` project to `generation_failed`
once its heartbeat is older than `GENERATION_STALE_S` (default 240s), covering threads killed
by a Space restart.

**Consequences.** No request-timeout risk. Real, pollable progress. Credits are still deducted
only on success (moved into the job's finish path). Background threads do not survive a Space
restart; the staleness guard plus the client retry panel recover the user. `debug`/reloader is
left on; threads still run.

---

## ADR-002 — True iterative image refinement with model fallback
**Date:** 2026-07-04 · **Status:** Accepted

**Context.** A single multimodal call is unreliable for producing exactly 5 illustrated steps.
The primary image model (`GENERATION_MODEL`, "Nano Banana 2" = `gemini-3.1-flash-image-preview`)
is higher latency and sometimes returns text-only turns.

**Decision.** Generate in phases inside `_run_guide_generation`:
- **Phase A (plan):** a fast text-only call on `PLAN_TEXT_MODEL` (`gemini-3.1-flash-lite`) returns
  the tools list and exactly 5 numbered steps. Reuses the existing regex extraction and
  `parse_numbered_steps`.
- **Phase B (images):** one chat session on `GENERATION_MODEL`, one `send_message` per step so each
  turn yields exactly one image with visual continuity. Each call runs under a timeout
  (`IMAGE_CALL_TIMEOUT_S`, default 28s) with one retry, then falls back to `FALLBACK_IMAGE_MODEL`
  (`gemini-2.5-flash-image`, "nano banana original") for the remaining steps. A step that still
  yields no image keeps its text with an empty `imageUrl`; **steps are never truncated**.
- **Phase C (upload):** reuses the existing per-step image-upload + Deepgram-TTS parallelism.

All model ids and the timeout are environment variables, tunable without a redeploy.

**Consequences.** Guaranteed 5 text steps, with a latency safety net. Cost per guide is higher
than a single call (multiple model turns) but predictable; track it. Fixes the min-truncation bug.

---

## ADR-003 — Country-scoped supplier catalogue grounding
**Date:** 2026-07-04 (country scoping added 2026-07-05) · **Status:** Accepted

**Context.** The tools list was plain strings. We want real supplier prices (anchor partner:
Electrosales, Harare) shown to users, but only to users in that supplier's market, the way
Home Depot shows to US users and Builders to SA users. A user in a country with no partner
should see the generic tools list.

**Decision.** New `catalogue/` RTDB root. Each item carries a 2-letter `country` ISO code
(default `ZW` via `DEFAULT_CATALOGUE_COUNTRY`) plus `supplier`, `city`, keywords, price, etc.
Admin-only endpoints: CRUD, AI extract from an uploaded image or PDF (Gemini with
`response_mime_type=application/json`; PDFs go through `types.Part.from_bytes`, no new deps),
and bulk save after review. `match_tools_to_catalogue` is a cheap token-overlap scorer that
returns the best in-stock item per tool (carrying its `country`), cached on the project as
`toolMatches` at generation time and recomputed on demand via `GET /api/projects/<id>/tool-matches`.
The **client** detects the viewer's country and filters matches; the backend stays country-agnostic.

**Rejected alternative.** A per-user `city` field on the user profile (built, then reverted).
The user wanted automatic locale detection, not a manual setting. `PUT /api/user/profile` is back
to display-name only.

**Consequences.** Onboarding a new market is a data operation: load that supplier's catalogue
tagged with its country code. No server change per user. The matching scan is O(tools × items),
fine to roughly 1–2k items; add a keyword index if the catalogue grows large.

---

<!-- Template for new records:
## ADR-00N — Title
**Date:** YYYY-MM-DD · **Status:** Accepted
**Context.** ...
**Decision.** ...
**Consequences.** ...
-->