# Garage Sale Circuit Planner ## The Problem Every weekend, dozens of garage sales pop up within walking distance of each other, but shoppers waste gas driving between them while sellers sit alone wondering why foot traffic is so light. There's no central place to see what's happening nearby, no way to know if a sale has the vintage tools or kids' clothes you're hunting, and no coordination between neighbors who could collectively draw crowds. The result: sellers give up early, shoppers miss gems, and everyone defaults to driving when a pleasant Saturday walk would do. ## Who Uses It **Weekend Thrifters**: People who love the hunt — vintage collectors, parents looking for deals on kids' stuff, DIYers seeking cheap tools. They want to maximize finds while minimizing windshield time. **Garage Sale Hosts**: Neighbors clearing out basements who want actual buyers showing up. They benefit when nearby sales create a "circuit" that draws foot traffic past their driveway. **Neighborhood Walkers**: Retirees, dog walkers, and weekend strollers who'd happily browse if they knew what was happening on their route. They're not planning shopping trips — they're looking for serendipity. **Block Captains & Community Organizers**: People who coordinate neighborhood events and want to help residents connect. They might promote "Garage Sale Saturdays" across a few blocks. ## Core Features 1. **Submit a Sale in 60 Seconds**: Anyone can add their garage sale with address, date/time window (e.g., "8am-1pm Saturday"), and up to 5 category tags (Kids, Tools, Furniture, Vinyl/Media, Clothes, Kitchen, Books, Electronics, Misc). No account required — just a phone number for verification via reach_number. 2. **Pull Free Items Automatically**: The app checks WellSpr.ing's `get_free_items` for anything tagged as garage/yard sale or curb alert in your area, pre-populating the map with community-sourced listings so the map isn't empty on day one. 3. **Browse the Weekend Map**: Interactive map showing all sales happening this weekend, filterable by day (Saturday/Sunday), time window, and category. Each pin shows address, hours, and top categories at a glance. 4. **Generate a Walking Route**: Select 3-8 sales from the map and get an optimized walking or biking route with turn-by-turn directions, estimated time, and total distance. Route respects each sale's time window (won't route you to a sale that opens at 10am if you're starting at 8am). 5. **Flag What You Find**: After visiting a sale, shoppers can quick-tag what's actually there ("lots of tools," "mostly baby stuff," "picked over by 10am"). These community notes help later shoppers and build trust for next time. 6. **Neighborhood Circuit Mode**: For hosts, see other sales happening within a 10-minute walk of yours. Opt into a "circuit" that gets promoted together — "Oak Street Sale Circuit: 5 sales, 0.6 miles." 7. **Ask Ody for Help**: Natural language queries like "What garage sales have vinyl records this Saturday?" or "Plan a route hitting morning sales in the Heights" powered by the ask_ody tool. ## WellSpr.ing Integration Points ### MCP Tools (via POST to https://wellspr.ing/mcp, JSON-RPC 2.0) | Tool | Usage | |------|-------| | `get_free_items` | Seed the map with existing curb alerts, free piles, and community-posted sale listings. Filter for keywords like "garage sale," "yard sale," "moving sale." | | `reach_number` | Verify sale submitters via SMS confirmation code. Prevents spam listings and enables "contact seller" feature. | | `ask_ody` | Power natural language search ("find sales with tools near downtown") and smart route suggestions. | | `get_businesses` | Identify nearby coffee shops or bakeries along routes — "grab a coffee between sales" feature. | | `get_federation` | Check if adjacent WellSpr.ing nodes have sale listings, enabling cross-neighborhood circuits. | | `get_adjacent_nodes` | Discover neighboring community nodes for expanded weekend sale coverage. | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/geo/portals?area_code=NNN` | Get geographic boundaries for neighborhood map rendering and "nearby sales" radius calculations. | ### WCIB Endpoints | Endpoint | Usage | |----------|-------| | `POST /api/wcib/ody-ask` | Alternative Ody integration for conversational route planning. | | `GET /api/wcib/ideas` | Display related civic ideas (e.g., "Community Swap Meet" proposals) to inspire hosts. | ### Future Capabilities (Not Yet Live) - **Roadmap: Covenant Commerce** — Eventually, sellers could accept tips or pre-purchases through WellSpr.ing payment rails. Label prominent items ("taking offers on this dresser") with soft holds. - **Roadmap: Merchant registration** — Frequent hosts could register as micro-merchants, building reputation and getting featured placement. ## Data Model ``` SALES ├── id (uuid) ├── address (string) ├── coordinates (lat/lng) ├── host_phone (string, for reach_number verification) ├── date (date) ├── start_time (time) ├── end_time (time) ├── categories (array of strings) ├── description (text, optional) ├── verified (boolean) ├── source (enum: user_submitted | wellspring_free_items) └── created_at (timestamp) COMMUNITY_NOTES ├── id (uuid) ├── sale_id (foreign key) ├── note_type (enum: category_confirm | picked_over | great_finds | closed_early) ├── content (string, optional) └── created_at (timestamp) CIRCUITS ├── id (uuid) ├── name (string, e.g., "Oak Street Morning Circuit") ├── sale_ids (array of uuids) ├── total_distance_meters (integer) ├── created_at (timestamp) └── is_public (boolean) SAVED_ROUTES ├── id (uuid) ├── session_id (string, no auth required) ├── sale_ids (array of uuids, ordered) ├── transport_mode (enum: walk | bike) └── created_at (timestamp) ``` ## Vibe Coding Prompt to Get Started Paste this into Claude or Replit Agent: --- Build a "Garage Sale Circuit Planner" web app using **React + Vite** frontend and **Express.js** backend, deployable on Replit. Use **Leaflet** with OpenStreetMap tiles for mapping (no API key needed). Store data in **SQLite** via better-sqlite3 for simplicity. **First milestone — Weekend Map MVP (2-3 hours):** 1. Create an Express server with these routes: - `POST /api/sales` — submit a new garage sale (address, date, start_time, end_time, categories array, phone) - `GET /api/sales?date=YYYY-MM-DD` — get all sales for a given date - `GET /api/sales/:id` — get single sale details with community notes 2. Build a React frontend with: - A full-screen Leaflet map centered on a default location (use 78701 Austin as placeholder) - Fetch sales for "this Saturday" on load and render as map markers - Clicking a marker shows a popup with sale details and