# Stoop Sale Swap: Turn Leftovers Into Pickups ## The Problem Every weekend, thousands of garage sales end with boxes of unsold items that sellers face a frustrating choice about: haul everything back inside, donate (if a charity is even open), or set it at the curb hoping someone grabs it before trash day. This creates a massive coordination failure — perfectly good items go to landfills while neighbors who would've happily picked them up never knew they existed. The window between "sale over" and "garbage truck" is typically just a few hours, but there's no tool designed for this hyper-local, time-sensitive handoff. ## Who Uses It **Garage Sale Sellers (The Posters)** Parents clearing out kids' outgrown clothes, downsizing seniors, people moving soon. They're exhausted after a long sale day and just want stuff gone — not hauled to Goodwill or back to the garage. They'll spend 2 minutes posting photos if it means items disappear from their driveway. **Neighborhood Pickers (The Grabbers)** Thrift hunters, DIYers looking for project materials, parents of young kids watching for toys, people furnishing their first apartment cheap. They check local listings regularly and will drive 10 minutes for free furniture or a specific category they're watching. **Neighborhood Connectors** Block captains, Buy Nothing group admins, and community gardeners who share listings in group chats and help elderly neighbors post their leftovers. They're the human amplification layer. ## Core Features 1. **Quick-Post Leftover Bundles**: Snap 1-4 photos of items left on your driveway/stoop, add a one-line description ("kids toys, some clothes, random kitchen stuff"), set your address, and post — all in under 90 seconds. No account required for posting; just enter phone number for pickup coordination. 2. **Time Window Alerts**: Every post has an expiration ("available until 6pm today" or "on curb until trash pickup Tuesday 7am"). The app prominently displays countdown timers so grabbers know urgency is real. 3. **Category Watch Lists**: Neighbors save categories they care about (furniture, tools, baby gear, books, plants, craft supplies). When a new post matches within their radius, they get a browser notification or can check a filtered feed. 4. **One-Tap Claim with ETA**: Grabber taps "I'm coming" which sends their ETA to the poster. This isn't a binding reservation — items stay visible to others — but it signals that someone's en route so sellers don't leave early. Claim shows "Jamie is 12 min away." 5. **Curb Status Toggle**: Posters can mark items as "Items Still Here" / "Some Taken" / "All Gone!" so grabbers don't waste trips. Expired posts auto-archive but remain searchable for 48 hours (helps build neighborhood patterns). 6. **Neighborhood Radius Feed**: Default view shows free items within 1 mile, expandable to 3 miles. Uses WellSpr.ing geo/portals for neighborhood boundary awareness so posts can be tagged with neighborhood names. 7. **Cross-Post to WellSpr.ing Free Items**: One checkbox lets posters syndicate their listing to the broader WellSpr.ing free items pool, reaching people beyond the immediate app audience while keeping the primary interface focused on same-day urgency. ## WellSpr.ing Integration Points ### MCP Tools (via POST to `https://wellspr.ing/mcp` using JSON-RPC 2.0) | Tool | Usage in Stoop Sale Swap | |------|--------------------------| | `get_free_items` | Pull existing free item listings to show in the feed alongside app-native posts. Prevents duplicate ecosystems — your app augments, doesn't replace. | | `submit_business` | *Repurposed*: For users who do regular estate sales or cleanouts, register them as a "Free Stuff Poster" in the local business directory so neighbors can follow their future posts. | | `get_federation` | Discover adjacent WellSpr.ing nodes. If someone's browsing from a neighboring town, show them posts from their local node first. | | `get_adjacent_nodes` | Power a "See items in nearby neighborhoods" expansion feature. | | `ask_ody` | Let users ask "What free stuff is usually available on weekends in my area?" — Ody can summarize patterns from historical data. | | `reach_number` | Facilitate anonymous contact between poster and grabber without exposing personal phone numbers. | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/geo/portals?area_code=NNN` | Retrieve neighborhood boundary data to auto-tag posts with neighborhood names and power the radius-based feed. | ### WCIB API | Endpoint | Usage | |----------|-------| | `POST /api/wcib/ody-ask` | Power the "Ask for tips" feature: "What's the best way to post furniture for quick pickup?" | | `GET /api/wcib/ideas` | Show related civic tech ideas to engaged users ("Like this? Check out other neighbor-helping projects"). | ### Future Integration (Roadmap: not yet live) - **Pickup scheduling rails**: Coordinated time-slot booking for grabbers would reduce poster interruptions. Not currently available via API. - **Reputation/trust scores**: Track successful handoffs to surface reliable posters. Would require a future identity layer. - **Donation center routing**: Auto-suggest open donation centers for items unclaimed by expiration. Would need a civic services data enhancement. ## Data Model ### `posts` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | poster_phone | string | Hashed; used for reach_number relay | | description | text | One-liner describing items | | photos | array[url] | 1-4 image URLs | | categories | array[enum] | furniture, toys, clothes, books, tools, kitchen, electronics, plants, other | | location_lat | decimal | | | location_lng | decimal | | | neighborhood | string | Populated from geo/portals | | available_until | timestamp | Expiration time | | status | enum | active, some_taken, all_gone, expired | | syndicated_to_wellspring | boolean | Whether cross-posted to get_free_items pool | | created_at | timestamp | | ### `claims` | Field | Type | Notes | |-------|------|-------| | id | uuid | | | post_id | uuid | FK to posts | | grabber_phone | string | Hashed | | eta_minutes | integer | Estimated arrival | | status | enum | en_route, arrived, completed, canceled | | created_at | timestamp | | ### `watch_lists` | Field | Type | Notes | |-------|------|-------| | id | uuid | | | user_identifier | string | Browser fingerprint or optional phone | | categories | array[enum] | What they want alerts for | | radius_miles | decimal | 1, 2, or 3 | | center_lat | decimal | | | center_lng | decimal | | | notification_enabled | boolean | | ### `neighborhoods` | Field | Type | Notes | |-------|------|-------| | area_code | string | From geo/portals | | name | string | Display name | | bounds | polygon | Boundary geometry | ## Vibe Coding Prompt to Get Started Paste this into Claude or Replit Agent: --- **Build a "Stoop