SlabUploader/docs/IMPL-PLAN.md

Implementation Plan

Status: SPEC · Gate A freeze 2026-08-31 · hybrid rewrite pass 2026-09-01 · SlabUploader

Phase 0 and the Gate C / Phase 1–2 / Phase 6 sections below are authoritative for hybrid topology. Phases 3–5 still need a full hybrid rewrite in a later docs commit; until then implement only Phase 0 plus sections marked rewritten here. Do not implement deferred stubs (offline PWA, OCR, ruler) or any server happy-path measure/crop as SoT.

The build plan a professional (or a fresh Hermes session) executes against. Each phase has: goal, deliverables, acceptance criteria (testable), and exit gate. Ordering is by dependency. Do not skip ahead. Definition of done for every phase: code + tests + real execution output in the PR/commit message + docs updated.

Ground rules (from AGENTS.md):

• Deterministic core is unit-tested before any UI consumes it.
• No feature without a passing test and shown output.
• Inference stays toggleable; the full suite must pass with it disabled.
• One phase = a reviewable, shippable increment.

---

Phase 0 — Hybrid skeleton and client deterministic core (= Gates A+B)

Goal: scaffold the hybrid app and ship a tested client-authoritative TECH-SPEC pipeline (mask → axis → sqft/bdft → 3:4 PNG) plus a minimal FastAPI store/settings shell. No Woo publish, no inference, no offline/OCR/ruler.

Gate A (docs): AGENTS.md + this Phase 0 rewrite + review package locks (signed 2026-08-31). Gate B (infra/code): items below.

Scope — in:

• Repo layout: frontend/ (SvelteKit), backend/ (FastAPI), deploy/ stubs; docs stay SoT.
• Client pure modules implementing TECH-SPEC: constants, sheet/chroma/black + sliders, mask confirm hooks, length axis, scale, 6" widths, sqft, bdft = sqft × thickness_in, pricing rec from species $/bdft, 3:4 PNG / 80% fill / ≥1600 guard (no upscale).
• FastAPI: app factory, logging, config, GET /api/health, SQLite + alembic skeleton, settings stub with AES-GCM round-trip (secrets never returned on GET), draft store stub (accept client numbers + files — store only, do not recompute SoT).
• deploy/docker-compose.yml, Caddyfile.fragment, .env.example (placeholders only).
• Unit tests for TECH-SPEC TV-1 through TV-10 (esp. TV-3 bdft, TV-6/7 crop/no-upscale, TV-8 pricing, TV-10 rounding).
• Fixture photo set for Ty Gate B review.

Scope — out:

• Server happy-path pipeline / CLI that recomputes mask/crop/bdft as SoT.
• Real U2Net (stub OK; on-demand later).
• Woo create/publish, live taxonomy sync (mock/seed species list OK later).
• Inference Call 1/2, LoRA.
• Offline PWA, IndexedDB sync, OCR, ruler.
• Fake upscale / inventing pixels.

Deliverables:

• frontend/ scaffold + deterministic modules + unit tests TV-1…TV-10.
• backend/ FastAPI health + settings encryption + draft persistence stub + schema migration baseline.
• deploy/ compose + .env.example + Caddy fragment.
• Shown output in PR/commit: printed TV-3, TV-6, TV-7 (no-upscale/retake), and TV-10 on real fixtures.

Acceptance:

• Gate B: client (or shared pure) tests green for TECH-SPEC vectors; bdft identity holds (no /12); undersized source warns and refuses fake upscale; rounding matches TV-10.
• GET /api/health up in compose over HTTPS hostname after host inventory + Caddy merge.
• Settings AES round-trip; secret fields never appear in GET.
• Draft can store client-uploaded originals + PNGs + numbers without server recompute.
• Coverage target: deterministic modules ≥ 95% where practical; property checks (bdft monotonic in thickness/sqft; fill band; no upscale path).

Exit gate: Ty confirms Gate B math/image prep shown output on real fixtures; health + encrypted settings + draft store stub demonstrated (curl or thin UI).

Next: Gate C = early Phase 1 claimable publish — online hybrid capture + Woo draft

• SLAB-UAT-* on the configured store, inference OFF. Call 1/2 after Gate C, still inside POC.

---

Phase 1 — Gate C claimable path, then full API surface (rewritten)

Early Phase 1 / Gate C slice (claimable first draft listing)

Goal: one Woo draft listing Ty can open in store admin, with inference OFF. Online hybrid capture only. No OCR, ruler, or offline.

Deliverables:

• Online capture of 1–5 inventory photos (no airplane-mode requirement).
• Client sheet/sliders, mask overlay + user confirm, length axis overlay + confirm.
• Client sqft / bdft / 6" widths; 3:4 transparent PNG prep per TECH-SPEC.
• Manual SKU, length, thickness; manual taxonomy as needed for one listing.
• Calibrated draft upload: originals + processed PNGs + client-sent numbers. Server stores only (OPENAPI POST returns status: calibrated).
• Woo draft create with SKU prefix SLAB-UAT-* on the configured PROD store. Honor AGENTS Woo safety: SLAB-UAT-* forces draft even if Settings say publish.
• Inference remains OFF for this slice. Full suite still green with inference disabled.

Acceptance:

• Ty captures a real slab on phone (online), confirms mask + axis, sees client numbers.
• One SLAB-UAT-* product appears in Woo admin as draft with correct SKU/price/images enough for Ty to open and inspect.
• No Call 1/Call 2 required. No offline, OCR, or ruler path exercised.
• Duplicate SKU → stop with error; no second product.

Exit gate: Ty opens one draft listing in Woo admin. Gate C is green.

Phase 1 remainder (API / settings / taxonomy cache)

Goal: full slab CRUD + photo upload + settings + taxonomy cache read, still hybrid. No server happy-path math. No processing slab status.

Deliverables:

• Routers per OPENAPI: slabs (CRUD + upload + poll), photos (serve), pricing-rules, settings (AES-GCM + test stubs), taxonomy (cache read/write).
• Optimistic concurrency (client_rev / server_rev, 409 paths).
• Status machine only: draft → calibrated → ready → publishing → published | failed. Job queue only for publish, inference (later), and U2Net-on-demand. Never for measure/crop.
• Integration tests (httpx TestClient): create calibrated → poll → ready (manual fields); revision conflict; duplicate SKU; settings encryption round-trip (secret never returned).

Acceptance:

• OPENAPI.md endpoints implemented; a generated openapi.yaml matches the doc.
• Integration tests green; secrets never leak into any GET response (asserted).
• docker compose up (backend + a throwaway frontend stub) serves the API.
• PUT stores client-sent derived fields; does not recompute sqft/bdft/widths as SoT.

Exit gate: Ty drives the API with curl through a full calibrated → ready cycle (manual).

---

Phase 2 — Deferred: offline PWA / OCR / ruler (stub only)

Deferred post-POC. Do not implement for the online-only MVP.

Capture UX for POC lives in early Phase 1 / Gate C (online hybrid). See AGENTS.md §2.

Out of scope until a later product decision reopens offline:

• Workbox service worker, IndexedDB draft sync, airplane-mode capture
• Tesseract.js OCR for SKU
• OpenCV.js ruler / scale detection

No airplane-mode acceptance. No OCR or ruler exit gate in POC.

---

Phase 3 — Frontend: enrich, review, publish UI

Partial hybrid rewrite pending (docs commit 3). Goal and intent below stay valid. Do not reintroduce offline capture, server measure/crop, or a processing status. Prefer AGENTS + ARCHITECTURE + OPENAPI over any leftover offline-era wording.

Goal: the enriched review screen and publish action, wired to Phase 1 API.

Deliverables:

• Review screen: all fields editable (dimensions, species/character with confidence
  • manual override, price with recommendation, content with "Generate text" when inference is on, client-processed PNGs).
• Species/character inference UI (calls server; shows confidence; manual confirm below threshold). Call 1 uses all inventory photos @1024 when inference is enabled.
• Publish button (online-only), status polling, success/failure states, error detail.
• Settings UI: Woo creds + test, inference endpoint + test (vision check), pricing rules editor, brand voice/GEO. Prompts are server files, not UI settings.

Acceptance:

• Full round-trip in browser: capture → upload → review → edit → publish → local published (against a Woo sandbox/mock in tests; against real store in Phase 6).
• Inference disabled → review screen fully functional with manual species/character.
• Every field is editable and the override persists (asserted in a test).

Exit gate: Ty publishes a test slab to the real store as a Woo draft (SLAB-UAT-*) product. (Gate A lock: not pending/published for UAT.)

---

Phase 4 — WooCommerce integration (real)

Partial hybrid rewrite pending (docs commit 3). Payload and safety locks already match AGENTS. Keep woo_create_status + SLAB-UAT-* force-draft. No server happy-path image pipeline as SoT.

Goal: production Woo sync, taxonomy, dedupe, logging (FR24–28).

Deliverables:

• Woo client (httpx, Basic auth, timeouts), taxonomy sync, auto-assign, media upload, product create via woo_create_status (default draft; SLAB-UAT-* forces draft), dedupe, sync_log.
• POST /api/admin/taxonomy/sync against the real store.
• Integration tests against a Woo mock (respx) for success + error + duplicate paths.
• Partial-failure handling (orphaned media noted, per CONTENT-WOO §2.6).

Acceptance:

• Real UAT publish: product appears in store admin as draft under SLAB-UAT-*, correct SKU/price/images/category/tags; woo_product_id stored; sync_log written with payload_hash.
• Duplicate SKU publish → 409, no second product created.
• Woo error (bad creds / 500) → slab failed with detail; retry path works.
• All Woo integration tests green (mock + one live smoke).

Exit gate: Ty verifies a real Woo draft SLAB-UAT-* product in the store is correct.

---

Phase 5 — Inference (vision + optional content)

Partial hybrid rewrite pending (docs commit 3). Sequencing lock stands: inference OFF until Gate C is green; Call 1/2 still inside POC after Gate C. Call 1 = all photos @1024 (not top-down-only). Confidence threshold 0.7 (configurable) lives here.

Goal: scoped, toggleable inference with guardrails. Starts only after Gate C is green.

Deliverables:

• Vision wrapper: species/character (and related taxonomy) from all inventory photos downscaled to 1024 via the configurable OpenAI-compatible endpoint; model constrained to Woo taxonomy cache; returns confidence (threshold 0.7, configurable); logs request/response.
• Content wrapper: Call 2 reads prompts/call2.txt; LLM writes prose only, dimensions injected by deterministic templates. See docs/PROMPTS.md.
• test-inference endpoint (vision capability check).
• All inference code behind feature flags; suite passes with everything OFF.

Acceptance:

• With a local vision model configured: species/character suggestion appears with confidence; low confidence → manual confirm required.
• With inference OFF: full app works, tests green (explicit test asserts no network calls to the inference endpoint).
• Inference payloads stored for audit (asserted present after a call).
• Call 1 prompt file edits survive server restart (read fresh each invocation).

Exit gate: Ty runs species detection on 3 real slabs; results acceptable or manually corrected (that is the design).

---

Phase 6 — Deployment, UAT, hardening (rewritten, online only)

Goal: production deploy on the inventoried host + online user acceptance tests.

Deliverables:

• Host inventory pass (DEPLOYMENT §1 / deploy/INVENTORY.md) → final compose + Caddyfile.
• Deploy to https://${APP_HOSTNAME}; backup/restore runbook executed once (restore tested).
• UAT suite for the hybrid online path: scripted real slabs (≥3 species, ≥1 cathedral, ≥1 manual-width path, ≥1 duplicate-SKU attempt) with expected bdft/price/image-fill asserted. No offline capture, OCR, or ruler cases in POC UAT.
• Performance: client measure/crop budgets on device; optional U2Net-on-demand latency. No server happy-path “normalization 3–5s” budget. No OCR 1–2s budget.
• Docs: README, runbook, key-rotation verified.

Acceptance (measured):

• E2E capture→publish on iPhone and Android browsers works (online).
• Manual length override recalculates widths/sqft/bdft correctly (UAT asserts).
• Client crop: slab ~80% frame in ≥95% of UAT photos; shorter side ≥1600 when source allows.
• Woo product created with processed PNG images + correct taxonomy.
• Deterministic functions unit-tested; inference calls logged for audit when used.
• Backup restore demonstrated once.

Exit gate: Ty signs off on UAT results; v1 declared done.

---

Risks and mitigations

Risk	Impact	Mitigation
Green-sheet color varies / U2Net CPU latency high	slow or failed “Try harder”	chroma-key / black threshold primary on client; U2Net on demand only; never drop output_px_min below 1600 (undersized → retake)
No vision model available at deploy	species inference off	inference is toggleable; manual species/character fully functional — v1 not blocked
Woo partial publish (media up, product POST fails)	orphaned images, confusing state	sync_log + retained images for retry; manual cleanup note; no auto-delete
Local vision endpoint not up	inference off	configurable endpoint; deploy-time config; app works without it
SQLite contention under concurrent polls	slowdown	single owner, low volume; Postgres path documented
Host port/Caddy collision with co-resident apps (e.g. bolt.diy)	deploy conflict	Phase 0/6 inventory worksheet before any port bind

Ruler detection is deferred with offline/OCR (Phase 2 stub). Manual length is authoritative for POC. Do not treat ruler confidence as a POC risk row.

---

Definition of Done (v1, project-level)

• All 6 phases exit-gated by Ty (Phase 2 remains deferred stub unless product reopens it).
• Hybrid online acceptance met (measured in Phase 6 UAT).
• pytest + integration + UAT green; inference-off path green.
• Deployed on inventoried host, HTTPS, backed up, restore tested, runbook + key-rotation verified.
• Repo on gitea-atd (Ty_Tech/SlabUploader) is source of truth; docs current.