SlabUploader/Slab capture app PRD.txt

# Slab Capture & WooCommerce Publishing App — PRD

## Overview
Build a mobile-first, self-hosted web app that streamlines publishing one-of-a-one wood
slabs to a WooCommerce store. The app is a photo capture → calibration → inference →
publish pipeline.

**Primary constraints**
- No slab versioning in v1.
- No staff accounts or role complexity in v1.
- No bulk publishing; slab-by-slab submission only.
- No analytics in v1.
- No pricing tiers in v1 — flat price-per-bdft per species/wood-category.
- No app-level auth in v1 — app relies on HTTPS + trusted network.
- Single SKU per slab; duplicate SKU publish is blocked.
- Images are purged after successful publish (retained only while draft/retry).
- Deploy target: .201, Docker Compose + Caddy.

## Decisions log (2026-08-27, Ty)
1. No calibration photos — user manually enters SKU, length, thickness.
2. First photo is the measurement photo (must be top-down, lens parallel to broad side).
3. All photos go through background removal + 80% frame-fill crop.
4. Output: transparent PNGs, minimum 1600 px on the smaller dimension,
   cropped to 3:4 portrait (W:H 3:4 = 4:3 portrait) to match the WooCommerce
   template; configurable in settings.
5. Green or black sheet — algorithm auto-detects background color from image borders.
6. WooCommerce categories synced from store: Species (1 required, leaf-only), Wood Category (1+ required, leaf-only).
7. WooCommerce attributes: Edge Type (1 required), Figure (1+ required), Grade (1+ required), Thickness (1 required, rounded up to nearest Woo attribute range).
8. WooCommerce tags: fig-* and feat-* only (1+ required, e.g., fig-chat, feat-makcr).
   WooCommerce is the authoritative source; the design does not duplicate tag lists.
9. Two-call inference: Call 1 (vision, wood expert) → Call 2 (text, content gen). Both configurable.
10. Call 1 runs automatically after calibration **only if** inference is enabled.
    User reviews/corrects before triggering Call 2.
11. Inference timeout >45s or non-200 → error with retry. User can fill fields manually.
12. Woo product status set to "published" by default (configurable in settings).
13. Inference prompts are server-side text files, read fresh on each invocation.
14. Brand voice + GEO context injected into Call 2 prompt.
15. WooCommerce credentials (username + App Password) stored client-side in settings.
16. Inference endpoint: configurable OpenAI-compatible API (user provides base URL, key, model).
17. Test connection verifies text completion + vision support.
18. Offline capture not required for MVP.

## Open items
- (none — all resolved 2026-08-27)

## Goals and success metrics
**Goals**
- Reduce per-slab prep time (target: 20-30 to 5-10 minutes).
- Produce consistent, high-quality product pages (title, description, taxonomy, images).
- Keep deterministic core logic testable and auditable.
- Mobile-first UX with fast feedback.
- Allow Ty to host and control inference via a configurable OpenAI endpoint.

**Success metrics**
- Average time from first photo to published product <= 10 minutes.
- Dimension extraction accuracy within +/- 0.25 in.
- Photo normalization produces consistent 80% frame fill for 95% of inventory photos.
- Inference results accepted or corrected by user in <= 2 edits for 90% of slabs.

## Non-goals
- Multi-tenant SaaS or ERP integrations in v1.
- Generic SKU inventory management.
- Complex user roles or staff permissions.
- Bulk import/publish workflows.
- Offline capture for MVP.

## Users and core use cases

**Primary user**
- Ty (Owner/Expert): captures, configures, reviews, and publishes slabs.

**Core use cases**
- Capture: Stage slab on green or black sheet with lights, take 1-5 photos.
- Enter metadata: SKU, length (in), thickness (in).
- Calibration: App processes first photo - BG removal, longest dimension detection,
  area measurement (sqft), bdft calc, then processes all photos for BG removal + crop.
- Inference: Call 1 (vision) auto-runs, populating taxonomy/content. User reviews/corrects.
  Call 2 (text) user-triggered for title/description/short description.
- Review & publish: Final review screen with full override capability; publish to WooCommerce.
- Configuration: Settings for inference endpoint, Woo credentials, pricing rules,
  brand voice, GEO context, prompts.

## High level requirements summary
- Deterministic core: all measurement math, pricing, normalization, and WooCommerce sync
  must be deterministic and unit-tested.
- Scoped inference: species/category/attribute detection and content generation only;
  inference must be toggleable and use Ty's configured OpenAI endpoint.
- Mobile first: usable on modern iPhone and Android browsers.
- Single slab workflow: no batch publish in v1; each slab is captured, enriched,
  reviewed, and published individually.

## Functional requirements (detailed)

### Capture and calibration
- **FR1:** Camera capture for 1-5 inventory photos. First photo must be top-down,
  lens parallel to the slab's broad side.
- **FR2:** User manually enters SKU (3-24 chars, [A-Z0-9-]), length (in), thickness (in).
- **FR3:** App detects background color from image borders (green or black sheet).
- **FR4:** First photo: BG removal - find longest dimension - compute scale
  (longest_px / user-length) - compute area (sqft) - bdft = sqft * thickness / 12.
- **FR5:** All photos: BG removal - crop to 80% frame fill - save as transparent
  PNG, minimum 1600 px on smaller dimension, 3:4 portrait crop (configurable).
- **FR6:** User can retake the first photo or abort and start fresh.

### Dimensions and calculations
- **FR7:** Compute length (user-entered), area (sqft), and bdft deterministically.
- **FR8:** Thickness is always manually entered and treated as authoritative.
- **FR9:** All dimension math must be deterministic, unit-tested, and reproducible.

### Taxonomy (WooCommerce sync)
- **FR10:** Sync categories, attributes, and tags from WooCommerce and cache locally.
- **FR11:** Species category: 1 required, leaf-only selection.
- **FR12:** Wood Category: 1+ required, leaf-only selection (parents shown for grouping only).
- **FR13:** Edge Type attribute: 1 required.
- **FR14:** Figure attribute: 1+ required.
- **FR15:** Grade attribute: 1+ required.
- **FR16:** Thickness attribute: 1 required, mapped by rounding up user-entered
  thickness to nearest Woo attribute range.
- **FR17:** Tags: fig-* only, 1+ required.
- **FR18:** Auto-assign taxonomy based on inference results; allow manual override.

### Pricing engine
- **FR19:** UI to define bdft pricing rules by species and wood category.
- **FR20:** Deterministic bdft calculation and application of pricing rules to produce
  a price recommendation.
- **FR21:** Price recommendation editable by user; final price stored as authoritative.

### Inference (two-call architecture)
- **FR22:** Call 1 (vision): auto-run after calibration. Input: all inventory photos
  (downscaled to 1024px max, using original pre-crop photos), user metadata, synced
  Woo taxonomy. Output: species, wood categories, edge type, figure, grade —
  selected from Woo taxonomy, each with a confidence score. The model is
  constrained to choose from the synced Woo taxonomy lists.
- **FR22a:** Confidence threshold: 0.7. If the model's confidence for any field
  is below 0.7, the field is left blank and requires manual user selection.
  Threshold is configurable in settings for tuning.
- **FR22b:** Species bias: the prompt includes the full Woo species leaf list,
  constraining the model to select from known species only. This prevents
  hallucinated species and significantly improves accuracy.
- **FR22c:** Free-text observations: character, inclusions, voids, and checks
  are free-text observations. The server maps them to Woo `feat-*` product
  tags after the call returns. WooCommerce is the authoritative source for
  feat-* tag definitions; the design does not duplicate them.
- **FR23:** Call 2 (text): user-triggered. Can use curated Call 1 results OR
  manually-entered taxonomy. The LLM writes only descriptive prose
  (character, color, grain, use cases). The server assembles the final title,
  short description, and full description from deterministic templates with the
  LLM prose injected. Dimensions are never generated by the LLM.
- **FR24:** Inference prompts are server-side text files, read fresh on each
  invocation. A reset-to-default script restores the shipped defaults. Prompts
  are not user-facing settings; they are tuned by the owner directly.
- **FR25:** Progress indicator during inference calls (latency expected).
- **FR26:** Timeout >45s or non-200 - visible error with retry option. Retry is
  available if the inference endpoint was previously tested as connected.
  Intermittent failures are expected in low-connectivity environments.
- **FR27:** All inference results editable; no automatic publish of LLM output.
- **FR28:** Inference endpoint configured via settings: base URL, API key, model name.
  Test connection verifies text + vision support.

### Photo normalization and output
- **FR29:** Background removal: chroma-key for green/black, fallback to U2Net matting.
- **FR30:** Crop to 80% frame fill, slab centered, 3:4 portrait aspect,
  minimum 1600 px on smaller dimension.
- **FR31:** Output as transparent PNG (ideal for WooCommerce).
- **FR32:** Store both original and processed images. Purge after successful publish.

### WooCommerce sync and publish
- **FR33:** Authenticate to WooCommerce using consumer key + App Password.
- **FR34:** Publish is blocked if the slab SKU already exists (simple dedupe, no update path).
- **FR35:** Create WooCommerce product with SKU, title, description, short description,
  price, categories, attributes, tags, and normalized PNG images.
- **FR36:** Default product status: "published" (configurable in settings).
- **FR37:** Log sync results and surface errors; store WooCommerce product ID on success.

### Drafts, review, and publish
- **FR38:** Maintain a draft slab state with full metadata and photos.
- **FR39:** Provide a single review screen showing all fields; every field is editable.
- **FR40:** Publish action performs deterministic server-side processing and WooCommerce
  sync; update status to Published/Failed with error details.

### Configuration and hosting
- **FR41:** Settings UI for inference endpoint, Woo credentials, pricing rules,
  brand voice, GEO context, prompts.
- **FR42:** App deploys via Docker Compose on .201 with Caddy for HTTPS.
- **FR43:** All secrets stored encrypted at rest; all client-server traffic over HTTPS.

## Non-functional requirements
- **Performance:** Client capture and local processing within 1-2s; server normalization
  within 3-5s per slab; inference calls within 45s.
- **Reliability:** Deterministic logic fully unit-tested.
- **Security:** Encrypted secrets, HTTPS, minimal persistent credentials on client.
- **Maintainability:** Clear separation of deterministic code and inference code.
- **Usability:** One-hand operation, large touch targets, clear distinction between
  internal processing and customer-facing output.

## Architecture and tech stack

**Client (mobile web / PWA)**
- SvelteKit (mobile-first)
- TailwindCSS for UI
- Camera API for capture and immediate preview
- No OCR, no OpenCV on client

**Server (self-hosted, containerized)**
- FastAPI (Python) for deterministic image pipeline, bdft math, pricing,
  background removal, crop/normalize, WooCommerce REST integration,
  inference wrappers, taxonomy sync
- SQLite for v1 (slab records, pricing rules, taxonomy cache, sync history)

**Inference**
- Configurable OpenAI-compatible endpoint (user supplies base URL, key, model).
  Must support vision. Two calls: wood expert (vision) + content generation (text).
  All inference calls logged.

**Deployment**
- Docker Compose with frontend and fastapi services on .201.
- Caddy for HTTPS and reverse proxy.

**Security**
- AES encryption for stored secrets.
- No app-level auth in v1.
- HTTPS enforced.

### Pricing rule schema
id: uuid
species: string
wood_category: string
price_per_bdft: float
created_at: timestamp
updated_at: timestamp

## Key flows and acceptance criteria

### Capture -> Calibrate -> Infer -> Publish flow
1. New slab: user stages slab and opens app.
2. Capture: take 1-5 inventory photos.
3. Enter metadata: SKU, length, thickness.
4. Calibration: server processes first photo (BG removal, area, bdft),
   processes all photos (BG removal, crop, PNG).
5. Inference: Call 1 auto-runs (vision), populating taxonomy/content.
   User reviews/corrects. Call 2 user-triggered (text), generating
   title/description/short description.
6. Review: user edits/overrides any field.
7. Publish: user triggers publish; FastAPI syncs taxonomy, creates
   WooCommerce product, purges images. Status updated and logged.

### Acceptance criteria
- End-to-end slab capture to published product works on modern iPhone and Android browsers.
- Area measurement accuracy within +/- 0.25 in^2.
- Photo normalization produces 80% frame fill, transparent PNG, 1600px min on smaller dim.
- WooCommerce product created with normalized images, correct taxonomy, and correct content.
- Deterministic functions covered by unit tests; inference calls logged.

## Operational and debugging notes
- Local dev: Docker Compose with frontend and fastapi. Mobile testing over LAN/Tailscale.
- Logging: centralized logs per service; inference request/response payloads stored for audit.
- Testing: unit tests for deterministic math and image processing; integration tests
  for WooCommerce sync against a staging store.
- Secrets: store App Passwords and inference keys encrypted; rotate keys periodically.
- Monitoring: health endpoints and job queue visibility.