# Car Parts Price Comparator — Cross-Store Cart Assembly (Design Note) **Status:** Draft v1 · 2026-07-15 — general idea only; no per-store cart recon done yet. **Companion documents:** `DISTRIBUTION.md` (the local-browser distribution model this feature depends on), `PURCHASE-PLAN-FUNCTIONAL-SPEC.md` (the feature this extends), `MONETIZATION-PLAYBOOK.md` (workshop-tier and affiliate interactions), `WALLED-STORES.md` (the no-evasion policy, which binds here too). **Scope:** The concept, the user story, the hard design lines, and the adapter shape. Per-store cart-flow reconnaissance (the `TECHNICAL-SPEC.md` §1 equivalent for carts) is future work, gated on the Electron shell existing at all. > **Supersession note (2026-07-16):** Outbound URL tracking decoration was removed. Any future cart attribution flow requires a new explicit product and privacy decision. --- ## 1. The idea in one paragraph The desktop/mobile distribution (`DISTRIBUTION.md` §3) gives every user a **real, persistent, per-store browser session on their own machine**. That session can do more than read prices — it can act on the store *as the user*: hold a login, hold a guest cart, add items to it. So the Purchase Plan (Pirkumu plāns) stops being a shopping *list* and becomes a shopping *agent*: the user plans 9 parts across 3 stores, clicks once, and the app fills three carts — then hands over to the user, at each store's own checkout, to press Pay themselves. Price comparators universally stop at the click-through handoff; almost none do cross-store cart assembly, because almost none have a real browser on the user's machine. We do. ## 2. User story 1. User assembles a Purchase Plan as today: offers picked across stores, quantities set. 2. User clicks **"Sagatavot grozus"** (prepare carts). 3. Per store, sequentially and human-paced, the app's store session adds each planned item to that store's cart — as a guest by default, or under the user's own store account if they've logged in (see §4.1). 4. The plan view shows per-store status: ✅ cart ready (n items, total €) / ⚠️ item unavailable / needs attention. 5. User taps a store → the app opens that store's **cart page** in the visible browser window → user reviews and completes checkout **manually**. Login (optional, per store): the app opens the store's **own login page** in the embedded browser window; the user signs in exactly as they would in Chrome; the session cookie persists in that store's partition. Used when a store gates checkout behind accounts or the user wants order history/loyalty pricing. ## 3. Why this is technically nearly free - **Sessions already exist.** The BrowserHub-behind-WebContents/WebView design (`DISTRIBUTION.md` §3) already maintains a persistent, isolated session per store (`persist:` partitions) to keep Cloudflare clearance warm. Carts and logins are just more cookies in the same jar. - **Guest carts are the easy case.** Most stores maintain a cart against a bare session cookie — no login needed. "Without an account" is not the harder variant; it's the default. - **Known platform flows.** Several stores sit on stock platforms with well-understood cart mechanics (Magento: `form_key` + `POST /checkout/cart/add`; PrestaShop: cart controller). Where no clean endpoint exists, DOM automation on the product page inside the hidden view is the fallback. Recon to be done per store, in a future table mirroring `TECHNICAL-SPEC.md` §1. ## 4. Hard design lines (non-negotiable) ### 4.1 The app never sees a password The user authenticates inside the **store's genuine login page** rendered in the embedded browser. Keystrokes go from the user to the store; the app holds only the resulting session cookies, in the OS-level session partition — the same trust model as a browser profile. **No credential storage, no password-field reading, no autofill of secrets — ever.** For an open-source repo this is existential: the codebase must be able to survive hostile inspection with the truthful claim *"this app never sees your password."* ### 4.2 Fill carts, never press Pay Add-to-cart is reversible and costs nothing when wrong. Automated **checkout** means the app can spend the user's money on a mis-scraped offer (stale price, wrong variant, quantity error) — a category of harm this project will not carry. The human clicks the final button, always. This line is also what keeps every store comfortable: a tool that fills carts is *driving sales*; a tool that completes purchases is a bot. ### 4.3 Human-paced, user-initiated only One cart-fill per explicit user action; stores processed sequentially with normal delays; no background or scheduled cart activity. Stores' fraud systems watch cart behaviour, and tripping one on a **logged-in account** creates real user harm (locked accounts, cancelled orders). This also keeps the feature squarely inside the standing no-evasion policy (`WALLED-STORES.md` §1): a real browser, the user's own session, doing exactly what the user asked, at a human's tempo. ### 4.4 Affiliate attribution ordering If the affiliate floor (`MONETIZATION-PLAYBOOK.md` Phase 1) is live, attribution rides on click-through redirect cookies. An API-level add-to-cart can silently bypass tracking and zero our own revenue. Rule: **navigate the session to the affiliate/UTM-tagged product URL first, then add to cart in the same session.** ## 5. Adapter shape Extends the runtime-agnostic adapter design (`DISTRIBUTION.md` §4): each store gains an optional **cart capability** alongside search — - *Cart descriptor:* how to add an item — endpoint + payload template, or a DOM-automation script for the product page; plus the store's cart-page URL for the handoff. - *Injected session:* the same per-store BrowserHub session used for fetching; no separate machinery. - Stores without a cart adapter simply keep today's behaviour (deep-link handoff). The capability is additive and per-store. **The honest cost: this roughly doubles the adapter-rot surface.** Cart flows break as often as search markup does, and each store now has two things to keep alive. Two consolations: the purity refactor pattern contains the damage the same way it does for search, and "cart adapters kept alive" makes the workshop-tier maintenance SLA (`MONETIZATION-PLAYBOOK.md` Phase 3) meaningfully fatter — cart assembly is precisely the kind of daily-workflow feature a workshop would pay to keep working. ## 6. Open questions (for the recon phase) 1. Per-store cart mechanics: clean endpoint vs. DOM automation, guest-cart support, variant/quantity encoding — needs live probing per store, results to be tabulated here. 2. Price-drift handling: the cart is filled from a possibly-stale offer; the store's cart shows the real price. The handoff review step (§2 step 5) is the mitigation — does it need explicit "price changed" detection, or is the user's own review at checkout enough for v1? (Lean: user review is enough for v1.) 3. Availability failures mid-fill: item out of stock at add time → mark ⚠️ in the plan and continue, or halt the store? (Lean: mark and continue.) 4. Mobile parity: same flow via hidden WebView per `DISTRIBUTION.md` §3.2 — verify guest-cart cookies survive WebView lifecycle on Android/iOS. 5. Whether any store's ToS explicitly addresses user-side cart automation — check during recon, store by store, as part of the usual delist-on-request posture.