From be221433ea902b859f6ddae3b8b41a56dd0c0696 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Wed, 2 Sep 2026 00:32:49 +0000 Subject: [PATCH] docs(#15): mask is load-bearing; inline knobs, live re-run, U2Net deferred TECH-SPEC states BG removal defines the measurement footprint and silent corruption failure mode. Four knobs stay on capture with live overlay on the source photo. POC is client-side only; U2Net try-harder deferred, not deleted. ARCHITECTURE swimlane and clarifications match. --- docs/ARCHITECTURE.md | 34 +++++++++++++++++++++++-------- docs/TECH-SPEC-PIPELINE.md | 41 ++++++++++++++++++++++++++------------ 2 files changed, 54 insertions(+), 21 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b5d852e..c469e93 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -173,19 +173,37 @@ ready → publishing → published. ## 7. Taxonomy cache (manufactured last-modified) -Woo category/tag/attribute `date_modified` is not a reliable client cache key (the store does not bump it for every edit we care about). FastAPI **manufactures** a `taxonomy_updated_at` timestamp: +Woo REST exposes **no usable last-modified** on categories, attributes, or tags +(only products carry `date_modified`). The client never talks to Woo. FastAPI is +the sole freshness source and **manufactures** one anchor timestamp +(`taxonomy_updated_at` / `cache_anchor`). -- Bump **only** when a stored-subset row actually changes (species/wood-category leaves, five attributes + terms, `fig-*`/`feat-*` tags). -- A no-op sync (same rows) **does not** bump. -- Client re-pulls if the returned anchor is newer than its snapshot. +- Anchor bumps **only** when a row-level change is detected in the **stored + subset** of cache fields (whatever columns the cache tables actually keep: + species/wood-category leaves, five attributes + terms, `fig-*`/`feat-*` tags). + Scope is schema-driven: adding a cache column later automatically includes it. +- Spelling/name edits, additions, and deletions all bump. Diff must catch missing + rows (deletions), not only changed rows. +- A no-op sync (stored subset unchanged) **does not** bump, so the client does + not churn. +- Client reads the anchor. If it advanced past the client's last value, re-pull + the **full** taxonomy cache. One timestamp governs categories, attributes, and + tags together. +- Do not invent a Woo-side taxonomy timestamp or a per-table anchor. **Triggers** -1. `POST /api/v1/settings/test-woo` always runs a taxonomy resync after a successful connection test. -2. Publish path: opportunistic resync if the last successful bump is older than **1 hour**. -3. Optional: app launch and a Settings “Refresh taxonomy” control. +1. `POST /api/v1/settings/test-woo` **always** resyncs taxonomy after a successful + connection test (unlocks the species list). +2. Publish / product submit: opportunistic resync if the last successful sync is + older than **1 hour**; bump anchor only if the stored subset changed. +3. Optional: app launch check (sync only if stale) and a Settings “Refresh + taxonomy” control. Not required for POC. +4. Do **not** sync on every screen navigation. -Species pickers and Call 1 option lists are **exactly** this cached set. No hardcoded mill list. +Species pickers and Call 1 option lists are **exactly** this cached set. No +hardcoded, invented, or fallback species list. A new Woo species is selectable +only after the next sync that lands it in the cache. ## 8. Shared validation module diff --git a/docs/TECH-SPEC-PIPELINE.md b/docs/TECH-SPEC-PIPELINE.md index 5af049b..67c7264 100644 --- a/docs/TECH-SPEC-PIPELINE.md +++ b/docs/TECH-SPEC-PIPELINE.md @@ -32,9 +32,14 @@ Inference, Woo payload, API, and schema live in other docs. - bdft is never rounded up to whole board feet. - Pixel→inch scale is an implementation detail. Users never see pixels. -## 3. Background removal +## 3. Background removal (load-bearing) -The user must see where the cut will land and be able to fix it. Edge quality is the foundation of sqft and bdft. +Background removal is the **load-bearing phase** of the image pipeline. The mask +defines the slab's pixel footprint. Length axis, 6" width samples, sqft, and bdft +all derive from that footprint. A clipped or over-inclusive mask silently shifts +the bounding rectangle and width samples with no later numeric check to catch it. +The user's eye on the overlay is the only validator. There is no confidence score +and no auto-gate on mask quality. ### 3.1 Auto-detect sheet 1. Sample a 2–5% strip on all four borders. @@ -44,14 +49,19 @@ The user must see where the cut will land and be able to fix it. Edge quality is 5. Else prompt: pick green or black. ### 3.2 Visual feedback (required) -- Overlay the mask on the photo (what will be removed vs kept). -- Show the slab edge clearly — that edge is the measurement boundary. +- Overlay the mask on the **source photo** (included vs excluded pixels), not only + a cropped result. +- Show the slab edge clearly. That edge is the measurement boundary. - User confirms the edge before length / area run. ### 3.3 Capture knobs (inline, live, persisted) -Factory values live in code. If the user changes them, the new values persist in localStorage until reset (Settings). +Factory values live in code. If the user changes them, the new values persist in +localStorage until reset-to-default. -All four knobs are **on the capture screen next to the overlay**, not in Settings. Changing any knob **immediately re-runs** §3.4 on the current photo and refreshes the overlay on the source image. No apply/save step. No server round trip in POC. +All four knobs are **on the capture screen next to the overlay**, not behind a +Settings navigation. Changing any knob **immediately re-runs** §3.4 on the current +photo and refreshes the overlay on the source image. No apply/save step. No server +round trip for mask tuning in POC. 1. **Sheet** — auto / green / black. 2. **Sensitivity** — one slider; tighter vs looser detection (green: HSV range width; black: brightness cutoff). @@ -61,7 +71,11 @@ All four knobs are **on the capture screen next to the overlay**, not in Setting ### 3.4 Algorithms - **Green:** chroma-key in HSV. Border flood-fill so only sheet pixels connected to the image edge are removed (protects green-ish grain inside the slab). - **Black:** grayscale threshold. Same flood-fill (protects dark grain). -- **Fallback (POC):** retake. U2Net matting is last resort **post-POC** (one photo in, mask out; sliders still apply). Do not implement in Gate C. +- **POC path:** client-side only (sheet detect + four knobs). If the edge is still + wrong after tuning, **retake**. +- **Post-POC fallback (deferred, not deleted):** U2Net matting on one photo via + FastAPI. Mask returns; knobs still apply on the client. Do not ship the control + in Gate C / first listing. Do not remove the contract from architecture. - Morphological close, then feather per the setting. ### 3.5 Edge quality @@ -212,10 +226,11 @@ Price 12.345 → **12.35**. | Topic | Doc | |---|---| -| Call 1 / Call 2 prompts, taxonomy mapping | Content / Woo | -| Woo payload, publish, duplicate SKU | Content / Woo, OpenAPI | -| SQLite tables, status machine | Data Model | -| HTTP contract | OpenAPI | -| Client vs server topology | Architecture | -| Auto-dimension overlay, figure-weighted price | Impl plan (v1.5) | +| Call 1 / Call 2 prompts, taxonomy mapping | PROMPTS, CONTENT-WOO | +| Portable Call 1→Call 2 context (full resend default) | ARCHITECTURE §9, PROMPTS | +| Woo payload, publish, 409/422 recovery | CONTENT-WOO, OPENAPI | +| SQLite tables, status machine | DATA-MODEL | +| HTTP contract, taxonomy `cache_anchor` | OPENAPI | +| Client vs server topology, validation module | ARCHITECTURE | +| Auto-dimension overlay, figure-weighted price | IMPL-PLAN (v1.5) | | Offline capture | non-goal (online-only POC; see AGENTS) |