master-plan.txt

Paint Intelligence Platform - Master Execution Plan
Date: 27 March 2026

1) Vision and Core Product Job
- Vision: Build a paint decision engine first, then expand into a dealer operating system.
- Core product job (current stage): Help a customer choose a paint color confidently in under 60 seconds.
- Expansion principle: Only add new modules after measurable proof from the current module.

2) Current Build Status
Phases 0–6 + scale hardening are complete on the product surface. Phase 7 (AI + differentiation)
is the active frontier (soft palette recommend + reminder notify scaffolding in progress).

Completed:
- Phases 1–3: decision engine, conversion layer, pilot analytics
- Phase 4: PostgreSQL backend (auth, leads, shades, dealer, events) + frontend sync + Docker/CI/monitoring
- Phase 5: CRM Lite (customers, sites, sessions/timeline)
- Phase 6: quotes → orders, inventory, credit ledger + reminder logging
- Scale hardening: pagination, refresh-token auth, Vite frontend modules, Fly/Render deploy

Current validation objective:
- Run pilot with 3–5 dealers on the full stack (signed in, server sync enabled)
- Measure repeat sessions, contact/share rates, and quote→ledger usage
- Gate Phase 7 deep AI / WhatsApp delivery on evidence dealers use ledger reminders weekly

See BACKLOG.md for prioritized engineering/product work outside the phase roadmap.

3) Product Scope Guardrails
Build now:
- Fast visual decision flow
- Better masking accuracy
- Per-wall control
- Conversion hooks to dealer

Do not build now:
- Full CRM suite
- Marketplace complexity
- VR/true 3D rendering
- Heavy AI workflows unrelated to immediate decision flow

4) Phase Roadmap

Phase 0 - Product Contract (Done)
- Lock scope: upload -> suggest -> preview -> compare -> share
- Define phase success metrics

Phase 1 - Decision Engine Hardening (Done)
- Improve wall selection reliability
- Add manual brush and per-wall editing controls
- Improve auto wall choosing quality
- Keep one-screen flow usable on mobile and desktop

Phase 2 - Conversion Layer (Done)
- Add Contact Dealer action
- Capture lead details: name, phone, selected shades (with brand + catalog metadata), preview snapshot
- Add simple local dealer inbox/list for captured leads
- Add session save for draft previews (auto-save + restore + new session)
- Lead package export (PNG snapshot + JSON sidecar with brand + shade metadata)
- Real shade catalog (63 shades: Asian Paints, Dulux, Berger, Nerolac)
- Shade search across full catalog by name, brand, or color family
- Basic cost estimator (litres + INR estimate for standard room, 2 coats)
- localStorage safety guards (graceful fallback when storage full)

Phase 3 - Pilot Validation (Done — infra complete; dealer pilot ongoing)
- Test with 3 to 5 local dealers
- Measure:
  - Time to customer decision
  - Share/contact action rate
  - Dealer feedback on close-rate impact
- Exit criteria: evidence of repeated real usage
- Phase 3 pilot infra built:
  - Session analytics engine (localStorage) tracking: session_start, shade_selected, share_exported, contact_opened, contact_saved
  - Pilot Analytics dashboard in Leads modal (Leads / Analytics tabs)
  - Metrics shown: sessions (30d), avg decision time, contact rate, share rate, 7-day bar chart
  - Analytics export: download JSON from Settings for pilot review
  - Dealer branding: shop name + dealer name shown in hero header, included in lead exports
  - Settings modal: configure dealer name/shop/phone, export or clear analytics
  - Dealer info embedded in all exported lead JSON packages

Phase 4 - Backend Foundation (Done — Jul 2026)
- Basic auth and tenant model ✓
- Lead APIs and preview metadata storage ✓
- Shade and dealer catalog APIs ✓
- Event tracking for funnel analytics ✓
- Phase 4 backend built (server/ — Node.js + Express + PostgreSQL):
  - POST /api/auth/register + POST /api/auth/login + GET /api/auth/me (JWT, 30-day token, bcrypt)
  - Tenant model: shop_name, dealer_name, phone, email — multi-tenant scoped
  - GET/POST/DELETE /api/leads + GET /api/leads/:id — per-tenant lead CRUD with snapshot storage
  - GET /api/shades — catalog API seeded from shades.json (63 shades), searchable by ?q=
  - GET/PUT /api/dealer — dealer profile API
  - POST /api/events — funnel event ingestion (session_start, shade_selected, share_exported, contact_opened, contact_saved)
  - GET /api/events/summary — 30-day funnel metrics: sessions, contact rate, share rate, avg decision time, 7-day bar data
  - Express also serves paint-preview-app/ as static files (run one port: 3001)
  - Docker Compose stack: app + Postgres + Redis + Prometheus + Grafana
  - GitHub Actions CI: lint, test, Docker build
- Frontend API sync layer (graceful degradation — full offline mode preserved):
  - apiRequest() helper with Bearer auth header
  - syncLeadToServer() — leads POST to backend on capture (includes cost estimate)
  - deleteLeadFromServer() — backend delete on local delete; clear-all propagates
  - syncLeadsFromServer() — on login/register, merges server leads; fetches snapshots via GET /api/leads/:id
  - syncDealerFromServer() — pulls dealer profile from server on session restore
  - syncEventToServer() — every analytics event also POSTed to backend (best-effort)
  - apiUpdateDealer() — dealer settings synced on save
  - loginToServer() / registerOnServer() / logoutFromServer()
  - Pilot Analytics uses GET /api/events/summary when signed in
  - Shade catalog loads from /api/shades when signed in (falls back to shades.json offline)
  - Server Sync section in Settings modal + standalone /login page

Phase 5 - CRM Lite (Done — Jul 2026)
- Customer CRUD (end_customer / contractor types) — create, edit, delete
- Site/project basics per customer (create via form)
- Preview session timeline linked to customer (session_start, shade_selected, lead_captured)
- Auto-link leads/sessions to customers by phone on server sync
- Frontend Customers modal with search, timeline, site management
- Lead detail links to the linked customer profile
- Offline customer cache (localStorage) — viewable offline; writes require sign-in
- Backend: /api/customers, /api/customers/:id/timeline, /api/sites, /api/sessions
- Full Jest suite (56 tests) green against PostgreSQL; coverage >70%

Phase 6 - Commercial Modules (In progress)
- Quote -> order basic flow (Done — Jul 2026)
  - quotes/quote_items + orders/order_items tables (migration 007), per-tenant sequential
    document numbers (Q-0001 / O-0001)
  - Backend: /api/quotes (list/create/read/update/delete, PATCH status, POST convert) and
    /api/orders (list/create/read/delete, PATCH status)
  - Totals computed server-side: line_total = qty x unit_price; subtotal; discount on subtotal;
    tax as % of discounted base; total. Client line totals are never trusted.
  - Convert = snapshot quote items + totals into a new order, lock quote as 'converted'
  - Frontend: Quotes button -> Quotes/Orders tabbed modal, quote builder (customer/site,
    line items from catalog or manual, discount/tax, live totals), detail view with status
    controls and Convert to Order. Requires sign-in.
  - Jest: quotes.test.js + orders.test.js (backend suite now 75 tests, coverage >70%)
- Inventory basics and stock status (Done — Jul 2026)
  - inventory_items + inventory_movements tables (migration 008); per-tenant optional SKU
    (partial unique index), reorder levels, selling/cost prices
  - Derived stock status: in_stock / low_stock / out_of_stock (quantity vs reorder level)
  - Backend: /api/inventory (list with ?q=/?status=, create, read w/ movements, update,
    delete), POST /:id/adjust (signed movement, blocks negative stock, audit trail), and
    GET /summary (counts by status + total stock value)
  - Quantity only moves through /adjust so every change is recorded with a running balance
  - Frontend: Inventory button -> item list (search + status filter + summary chips), item
    form (catalog-linked), detail view with receive/issue adjust controls and movement log
  - Jest: inventory.test.js (backend suite now 90 tests, coverage >70%)
- Credit ledger v1 and payment reminders (Done — Jul 2026)
  - ledger_entries + payment_reminders tables (migration 009); append-only per-customer
    account of debits (charges / order totals) and credits (payments / adjustments), each
    row storing the running balance after it was applied
  - Balance convention: positive = customer owes; negative = advance/credit. Balance is
    recomputed under a per-customer row lock so concurrent posts stay consistent.
  - Order totals post automatically: creating (or converting to) an order writes a debit;
    deleting the order writes a compensating reversal credit (ledger stays append-only)
  - Overdue = owes money AND a dated debit is past due; overdue accounts sort first
  - Backend: GET /api/ledger/summary (receivables snapshot), GET /api/ledger/customers
    (debtor worklist, ?overdue=true / ?q=), GET /api/ledger/customers/:id (statement),
    POST /:id/entries (debit/credit), POST /:id/reminders (log follow-up + balance snapshot)
  - Frontend: Ledger button -> summary chips + debtor worklist (search + overdue filter),
    account detail with record-payment / add-charge / log-reminder controls and statement
  - Jest: ledger.test.js (backend suite now 104 tests, coverage >70%)

Scale hardening (Done — Jul 2026)
- Pagination: shared lib/pagination.js; every list endpoint (customers, leads, quotes,
  orders, inventory, ledger/customers) takes ?limit=&offset= (default 50, max 200) and
  returns pagination:{total,limit,offset,hasMore} via a COUNT(*) OVER() window column.
  Frontend debtor worklist has a "Load more" pager (createPaginator + withPageParams).
- Auth lifecycle: short-lived access JWT (~15m) + rotating refresh tokens persisted as
  SHA-256 hashes (migration 010 refresh_tokens). /auth/refresh rotates + does reuse
  detection (replaying a rotated token revokes the whole chain); /auth/logout and
  /auth/logout-all revoke sessions. Frontend refreshes transparently on 401. Password
  policy raised to >=8 chars with a letter and a number. TTLs via ACCESS_TOKEN_TTL /
  REFRESH_TOKEN_TTL_DAYS.
- Frontend modularization: Vite build (minified + hashed assets, sourcemaps); logic split
  into ES modules src/api.js, src/utils.js, src/pagination.js with Vitest+jsdom unit tests
  (21 frontend tests). Server serves built dist/ when present, else raw source.
- Deployment: multi-stage Dockerfile now builds the frontend; fly.toml + CI Fly.io deploy
  (staging -> production, gated on FLY_API_TOKEN); DB_SSL flag for Fly-internal vs managed
  Postgres. Backend suite now 123 Jest tests.

Phase 7 - AI and Differentiation (In progress — Jul 2026)
- Soft palette recommendations (heuristic + optional OpenAI path) — scaffolding in tree
- Cost estimator in decision flow (Done — earlier phase; keep improving accuracy)
- Outbound reminder delivery (MSG91 SMS optional; WhatsApp click-to-chat; cron off by default)
- Dealer assistant prompts for quoting and follow-up (not started)

Phase 8 - Platform Expansion (Only after retention and monetization proof)
- Contractor assignment and tracking
- Customer-facing extended app flow
- Marketplace mechanics and ranking logic

5) Engineering Plan for Immediate Next Sprint (5 to 7 days) — Phase 1 (historical)
Day 1
- Stabilize wall-tab + brush interactions
- Add visual hint overlays while brushing

Day 2
- Add erase mode for brush
- Add undo/redo stack for mask edits

Day 3
- Add mask edge feathering for cleaner visual transitions
- Improve compare slider UX

Day 4
- Add Contact Dealer form UI
- Capture selected wall colors and preview reference

Day 5
- Add local lead list page
- Add export of lead + preview package

Day 6
- Manual QA pass with varied room photos
- Performance tuning on larger images

Day 7
- Pilot-ready release packaging
- Demo script and test checklist

Phase 2 Sprint Focus (current)
- Day 1-2: Contact Dealer button + modal form UI, auto-populate current shades/walls, snapshot capture on submit
- Day 2-3: Persist leads to localStorage, render inbox list + lead detail modal, delete action, basic count badge
- Day 3-4: Lead package export (download PNG snapshot + .json metadata file), copy-to-clipboard for quick share
- Day 4-5: Session draft save/restore (downscaled original + zones config; offer resume on load or explicit load)
- Day 5-6: Wire state (enable contact only when preview ready), mobile polish for modals/forms, success feedback
- Day 6-7: Manual QA on capture flow, update docs + metrics, ensure E2E still passes, prepare pilot notes

6) Success Metrics by Stage
Phase 1 metrics:
- Smooth interaction at typical photo sizes
- Accurate per-wall color assignment with tabs
- Brush mode resolves auto-mask misses quickly

Phase 2 metrics:
- Contact action completion rate from preview sessions
- Lead record quality and completeness

Phase 3 metrics:
- Dealer reports faster customer decisions
- Repeat usage during actual in-store interactions

7) Risks and Mitigations
Risk: Auto wall detection still fails in unusual lighting
- Mitigation: Keep brush mode primary fallback and add erase/undo

Risk: Too many controls create user confusion
- Mitigation: Keep one-screen flow and progressive controls

Risk: Feature creep into full platform too early
- Mitigation: Strict phase gates; no expansion without metric proof

8) Team Execution Rules
- Ship small increments every 1 to 3 days
- Keep changes reversible and testable
- Measure behavior before adding complexity
- Preserve app speed over feature count

9) Definition of Done for Current Milestone (Phase 2)
- Contact Dealer button is available after a preview is ready
- Lead form captures name + phone + current wall shades + a visual snapshot
- Captured leads appear in a local inbox list (persisted across reloads)
- User can view a lead, delete it, and export a lead package (PNG snapshot + JSON sidecar)
- Basic draft save/restore works for an in-progress preview session
- One-screen decision flow remains clean; conversion actions are progressive reveals

10) Immediate Next Action
- Build the Contact Dealer modal + capture + local leads inbox + package export in the preview app.
- Add minimal session draft persistence.