# Shade Tree Registry: Map Urban Cool Spots ## The Problem Urban heat islands kill more Americans each year than any other weather event, and the burden falls hardest on neighborhoods with fewer trees and more concrete. When it's 95°F on a shadeless sidewalk, elders walking to the pharmacy, construction workers on lunch break, and parents pushing strollers face real health risks. Cities lack granular data on where shade actually exists at street level—the kind of knowledge that only neighbors walking those blocks possess. ## Who Uses It **Maria, 72** — Walks to her doctor's office and grocery store. Needs to know which route has benches under trees where she can rest without overheating. **DeShawn, outdoor delivery driver** — Looks for shaded spots to park and cool down between runs. Knows every good overhang in his zone and wants to share them. **Priya, parent with a toddler** — Plans playground visits around shade availability. Won't take her kid to a park where the only bench is in full sun at 2pm. **Marcus, urban tree advocacy organizer** — Needs data showing which blocks have the least shade coverage to support grant applications for new tree planting. **Small business owners** — Coffee shops with shaded patios want visibility; hardware stores want to promote their awnings as rest spots for the community. ## Core Features 1. **Drop a shade pin with photo proof** — Anyone can mark a shady spot on the map by uploading a photo, selecting a type (mature tree, awning, building overhang, bus shelter, misting station), and noting what time of day the shade is effective (morning, midday, afternoon). 2. **Rate shade quality on three factors** — Users rate spots on: shade density (dappled vs. deep), seating availability (standing only, bench, multiple seats), and accessibility (wheelchair-friendly path to reach it). Ratings are 1-3 scale, keeping it fast. 3. **Plan a shady route between two points** — Enter start and destination addresses; the app suggests a walking route that passes through the maximum shade pins, with estimated added walking time vs. direct route. Shows "shade coverage score" as a percentage. 4. **Flag heat danger zones** — Mark stretches of sidewalk with zero shade for more than 2 blocks. These "heat gaps" visualize on the map in orange, creating advocacy data for where trees are most needed. 5. **Business shade partnerships** — Local businesses with shaded outdoor areas can register their spot and mark it as "public welcome to rest" with hours and any expectations (buy a water, or just come cool off). Links to their business listing. 6. **Seasonal shade calendar** — Trees provide different shade in June vs. September. Users can note "best months" for each spot, and the map filters to show currently-effective shade based on date. 7. **Export heat gap report by ZIP** — Generates a simple PDF showing all flagged heat gaps in an area with photos, designed for advocates to attach to city council testimony or grant applications. ## WellSpr.ing Integration Points ### MCP Tools (via POST to https://wellspr.ing/mcp as JSON-RPC 2.0) | Tool | Usage | |------|-------| | `get_businesses` | Pull local businesses to display as potential shade partners; show coffee shops, libraries, and community centers near high-heat routes | | `get_business_detail` | When a user taps a business shade spot, fetch hours, accessibility info, and contact details | | `submit_business` | Let business owners register their shaded outdoor area as a public cooling spot directly from the app | | `get_civic_ideas` | Surface existing community ideas about heat resilience, tree planting, or cooling centers to connect shade mappers with broader efforts | | `search_civic_services` | Find official cooling centers and water fountains that complement the crowdsourced shade data | | `get_city_services` | Pull city tree planting programs or urban forestry contacts to display on heat gap reports | | `ask_ody` | Power a help chat: "Where's the shadiest route from the library to the senior center?" Ody interprets the shade database | | `reach_number` | Display estimated community reach when sharing heat gap reports or shade route links | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/geo/portals?area_code=NNN` | Initialize map bounds and determine which neighborhood "portal" the user is contributing to | | `GET /api/officials` | When generating heat gap advocacy reports, auto-populate the relevant city council member's name and contact | ### Roadmap: Not Yet Live - **Covenant commerce for shade incentives** — Future capability could let businesses offer small discounts to users who check in at their shade spot, tracked via WellSpr.ing payment rails - **Federated shade data sharing** — `get_federation` and `get_adjacent_nodes` could eventually sync shade maps across neighboring communities, but current use case is single-neighborhood focused ## Data Model ### shade_spots | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | lat, lng | float | Location coordinates | | spot_type | enum | tree, awning, overhang, bus_shelter, misting_station, other | | photo_url | string | Required proof photo | | effective_hours | enum[] | morning, midday, afternoon | | best_months | int[] | 1-12 for seasonal relevance | | created_by | string | Anonymous user token | | created_at | timestamp | | ### shade_ratings | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | spot_id | uuid | FK to shade_spots | | shade_density | int | 1-3 scale | | seating | int | 1-3 scale | | accessibility | int | 1-3 scale | | rated_by | string | Anonymous user token | | rated_at | timestamp | | ### heat_gaps | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | path_geojson | json | LineString of shadeless stretch | | block_count | int | Estimated blocks with no shade | | photo_url | string | Optional documentation | | flagged_by | string | Anonymous user token | | flagged_at | timestamp | | ### business_shade_partners | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | wellspring_business_id | string | Links to WellSpr.ing business registry | | welcome_policy | text | "Buy a water" or "Just rest, no purchase needed" | | hours_available | string | When shade/cooling is open to public | | verified | boolean | Confirmed by business via submit_business | ## Vibe Coding Prompt to Get Started Paste this into Claude or Replit Agent: ``` Build a "Shade Tree Registry" web app for mapping urban cool spots. Tech stack: React 18 + Vite frontend, Express.js backend, SQLite database (easy Replit hosting), Leaflet.js for maps with OpenStreetMap tiles. First milestone: Core shade spot submission and map display 1. Create a full-screen Leaflet map centered on user's location (request geolocation permission) 2. Build a "Add Shade Spot" floating action button that opens a modal with: - Photo upload (required, use browser file input) - Spot type dropdown: Tree, Awning, Building Overhang, Bus Shelter, Misting Station, Other - Effective time checkboxes: Morning,