Product Requirements Document (PRD): YardSailer

1. Executive Summary

YardSailer is a hyper-local, community-driven web application designed to solve the logistical headache of "yard sailing." By aggregating disparate listings from platforms like Craigslist and Facebook Marketplace and combining them with user-generated content, YardSailer provides a centralized interactive map. Its flagship feature is a multi-stop route optimizer that uses advanced Traveling Salesperson Problem (TSP) algorithms to create the most fuel-efficient weekend itineraries for bargain hunters and professional resellers.

2. Problem Statement

Bargain hunters, antique collectors, and frugal families currently waste significant time and fuel manually scouring multiple websites (Facebook, Craigslist, Nextdoor) to find local sales. Once found, planning a route between 5–15 different residential addresses is mentally taxing and mathematically inefficient. Furthermore, the lack of real-time "active" status leads to "ghost stops"—sales that have already ended or sold out of items—creating a frustrating user experience.

3. Goals & Success Metrics

Centralization: Aggregate 80% of local digital sale listings in a target test market within 24 hours of posting.
Efficiency: Reduce average user route planning time from 30 minutes to under 2 minutes.
Accuracy: Maintain a <10% "ghost stop" rate through crowdsourced real-time status updates.
Engagement: Achieve a 30% month-over-month increase in user-generated sale photos and tags.

4. User Personas

"The Professional Picker" (Arthur): An antique dealer who needs to hit 20 sales before noon. Efficiency and "Tools/Antiques" filters are his priority.
"The Frugal Parent" (Sarah): Looking for kids' clothes and toys. She needs a route that starts after school drop-off and stays within a 5-mile radius.
"The Estate Seller" (Marcus): A professional estate sale manager who wants to list sales with high-quality photos and "Featured" placement to drive traffic.

5. User Stories

As a picker, I want to enter 10 locations and get an optimized driving route so that I can beat competitors to the best items.
As a parent, I want to filter sales by "Baby Clothes" so I don't waste time at sales selling only power tools.
As a seller, I want to upload photos of my best items from my phone so that I can attract more high-intent buyers.
As a community member, I want to mark a sale as "Sold Out" so that others don't waste gas driving to an empty driveway.

6. Functional Requirements

Core Features

Interactive Map: Clustered markers using PostGIS-driven server-side logic for high performance.
Route Optimizer: "One-click" optimization for up to 25 stops using Rust-based LKH-3 algorithms.
Smart Search: Filter by date, start time, and AI-categorized tags (Furniture, Electronics, etc.).
Real-time Crowdsourcing: Ability to report "Closed," "Still Open," or "Busy" status via WebSockets.
Mobile-First Listing Tool: Image upload with Cloudinary-powered AI sharpening and smart cropping.

Nice-to-Have Features

Weather Integration: Warnings for rain-outs based on OpenWeatherMap.
Automatic Scraping: Background workers for Craigslist and Facebook Marketplace (using stealth headless browsers).
Push Notifications: Alerts for "Multi-family sale" keywords in the user's zip code.

7. Technical Requirements

Tech Stack (2026 Standards)

Frontend: React ^19.2.3 (utilizing React Compiler 1.0) with Tailwind CSS ^4.1.18.
Mapping: Mapbox GL JS ^3.18.0 (using WebGL2 and 3D lighting).
Backend: Node.js (Express) with napi-rs bindings for high-performance route solving.
Database: PostgreSQL 18 + PostGIS 3.6 for geospatial queries.
Tile Server: Martin (Rust-based) for server-side MVT clustering.
Auth: Clerk (Auth/UI) + Supabase (RLS/Database) hybrid integration.
Infrastructure: Vercel (Frontend), Render (Backend), Redis (Caching/PubSub).

Integrations

Cloudinary: For AI-driven image transformation and lazy loading.
OpenWeatherMap API: Hyper-local precipitation alerts.
Google Maps Distance Matrix: To feed real-world travel times into the TSP solver.

8. Data Model

Entity: `SaleEvent`

id: UUID
location: Geometry(Point, 4326)
category_tags: TEXT[] (Indexed via GIN)
status: ENUM ('active', 'closed', 'busy')
media: JSONB (Cloudinary public IDs and metadata)
start_time: TimestampTZ

Entity: `OptimizedRoute`

id: UUID
user_id: FK -> Users
stop_order: UUID[] (Array of SaleEvent IDs)
total_distance: Float
polyline: TEXT (Encoded path for Mapbox)

9. API Specification (Key Endpoints)

| Method | Endpoint | Description | | :--- | :--- | :--- | | GET | /api/v1/sales/tiles/{z}/{x}/{y} | Serves MVT vector tiles with clustered sale data. | | POST | /api/v1/routes/optimize | Accepts array of Sale IDs; returns optimized sequence via Rust/LKH solver. | | PATCH | /api/v1/sales/{id}/status | Updates status; broadcasts change via WebSockets/Redis. | | POST | /api/v1/sales | Multipart upload for new listing + Cloudinary transform. |

10. UI/UX Requirements

Map-First Design: The map is the background; UI elements (filters, list) live in semi-transparent, Tailwind-styled floating glassmorphism panels.
Optimistic UI: When a user marks a sale as "Closed," the marker disappears immediately using React 19 useOptimistic.
Loading States: Use Cloudinary "blur-up" (LQIP) placeholders for listing images to ensure smooth scrolling.
Responsive Drawers: Mobile users interact with a bottom drawer that slides up to reveal route details.

11. Non-Functional Requirements

Performance: Map markers must cluster in <100ms for up to 10,000 active sales (achieved via Martin tile server).
Security: Sanitize all user-generated tags to prevent XSS; implement rate-limiting on the Add Sale endpoint to prevent bot spam.
Accessibility: WCAG 2.1 Level AA compliance; high-contrast map pins for color-blind users.

12. Out of Scope

In-app payments or transactions (YardSailer provides the map, but cash/Venmo happens on-site).
Social networking (No "User Profiles" or "Following" in V1).
Integration with private garage sale apps that require proprietary API access.

13. Risks & Mitigations

14. Implementation Tasks

Phase 1: Project Setup

[ ] Initialize project with React 19.2.3 and Tailwind CSS 4.1.18
[ ] Configure PostGIS 3.6 with PostgreSQL 18 on Supabase
[ ] Set up Martin Tile Server for MVT delivery
[ ] Configure Clerk for Passkey-first authentication

Phase 2: Core Map & Data

[ ] Implement ST_AsMVT functions in PostGIS for clustered sale delivery
[ ] Build the interactive Mapbox GL JS 3.18.0 canvas with 3D lighting
[ ] Create SaleEvent schema with GIN indexes on category tags
[ ] Implement multi-column GiST index (btree_gist) for category + spatial filtering

Phase 3: Route Optimization

[ ] Set up Node.js worker_threads for heavy computation
[ ] Integrate napi-rs with a Rust-based LKH-3 solver
[ ] Build the /api/v1/routes/optimize endpoint
[ ] Create the frontend "Route Drawer" with turn-by-turn list view

Phase 4: Social & Crowd Features

[ ] Implement React 19 useOptimistic for real-time status updates
[ ] Set up Redis Pub/Sub for WebSocket status broadcasting
[ ] Integrate Cloudinary AdvancedImage with g_auto smart cropping
[ ] Build the mobile-first "Add Sale" flow with chunked image uploads

Phase 5: Automation & Launch

[ ] Develop Craigslist scraper using Playwright Stealth
[ ] Implement OpenWeatherMap cron jobs for "Rain-out" flags
[ ] Perform security audit for CVE-2025-55182 (React2Shell)
[ ] Deploy frontend to Vercel and Martin/Backend to Render