smallengine/PLAN.md

SmallEngine - Implementation Plan

Phase 1: Project Foundation

• Scaffold Vue 3 + TypeScript + Vite project
• Initialize git repository
• Install and configure Tailwind CSS v4
• Set up shop.config.json schema and loader composable
• Create base layout with responsive Tailwind structure
• Configure PWA support (vite-plugin-pwa)

Phase 2: Lead Capture Form

• Design multi-step form flow (equipment > photos > schedule > contact > review)
• EquipmentStep — equipment type selector, make/model text inputs, service type selection
• PhotoUpload — mobile camera capture + file upload with local preview
• ScheduleStep — preferred date range for pickup/drop-off (start date + end date)
• ContactStep — name, phone, email, address fields
• PricingEstimate — display "starting at" price based on selected service (configurable per shop)
• ReviewStep — summary of all inputs before submission
• SuccessScreen — confirmation after submission
• Form state management (composable with reactive state)
• Step indicator with progress navigation

Phase 3: Form Submission & Lead Delivery (DEFERRED)

Build the UI first, then evaluate backend options (Formspree, Netlify Forms, Google Sheets, etc.)

• Integrate form backend (TBD)
• Submit form data as structured JSON
• Image upload integration (Cloudinary or similar — TBD)
• Success/error confirmation screens
• Email notification to shop owner on new lead

Phase 4: White-Label & Theming

• Load shop.config.json at app init
• Apply shop branding (name, logo, primary color) to layout
• Populate equipment types and services from config
• Populate pricing ranges from config
• Generate theme colors from config primary color at runtime (HSL conversion)

Phase 5: Polish & Mobile

• Mobile-first responsive testing
• PWA manifest and service worker
• Camera access for photo capture on mobile
• Accessibility audit (ARIA labels, keyboard navigation, color contrast)
• Loading states and form validation UX
• SEO meta tags (configurable per shop)

Phase 6: Deployment & Documentation

• Netlify deployment configuration (netlify.toml)
• Document fork-and-deploy workflow for shop owners
• Create example shop.config.json with comments
• Write deployment guide for Netlify, Cloudflare Pages, Vercel
• Test end-to-end: form submission to email receipt

---

Deployment Instructions

Prerequisites

• Node.js 18+
• Yarn package manager
• A free account on one of: Netlify, Cloudflare Pages, or Vercel
• A free Formspree account (or use Netlify Forms if hosting on Netlify)
• A free Cloudinary account (for image uploads)

Step-by-Step Deployment

1. Clone and configure

   git clone <repo-url>
   cd smallengine
   cp shop.config.example.json shop.config.json
   # Edit shop.config.json with your shop details
   

2. Set up Formspree (if not using Netlify Forms)

   • Create account at formspree.io
   • Create a new form
   • Copy form endpoint URL into shop.config.json → formBackend

3. Set up Cloudinary (for image uploads)

   • Create account at cloudinary.com
   • Get your cloud name from the dashboard
   • Add to shop.config.json → cloudinaryCloudName
   • Create an unsigned upload preset → cloudinaryUploadPreset

4. Build and test locally

   yarn install
   yarn build
   yarn preview
   # Visit http://localhost:4173
   

5. Deploy to Netlify

   # Option A: Netlify CLI
   npm i -g netlify-cli
   netlify deploy --prod --dir=dist
   
   # Option B: Git-based deploy
   # Push to GitHub, connect repo in Netlify dashboard
   # Build command: yarn build
   # Publish directory: dist
   

6. Set up custom domain (optional)

   • Add custom domain in hosting provider dashboard
   • Update DNS records as instructed
   • SSL is automatic on all recommended hosts

Environment-Specific Notes

• Netlify Forms: If hosting on Netlify, you can skip Formspree and use Netlify's built-in form handling (free: 100 submissions/month)
• Image size: Cloudinary free tier allows 25 credits/month (~25 transformations or uploads)
• No backend required: the entire app runs client-side

---

Decisions Log

• Lead delivery: Deferred until UI is complete
• Pricing: Configurable "starting at" ranges per service in shop.config.json
• Scheduling: Customer preference — date range for pickup/drop-off
• Multi-shop: Fork-per-shop (clone repo, edit config, deploy)
• Dashboard: Deferred — needed eventually, not in initial build