# Alley Adoption: Keep Hidden Paths Safe ## The Problem Alleys, cut-throughs, and shared paths between buildings often become dumping grounds, safety hazards, and eyesores because they exist in a responsibility gap—too small for city attention, too shared for any single property owner to claim. Burnt-out lights go unreported for months, trash accumulates, and what could be charming pedestrian shortcuts become places people avoid after dark. Without a simple way for neighbors to say "I'll watch over this stretch," these hidden corridors stay forgotten. ## Who Uses It **Alley Stewards**: Residents who walk through a particular cut-through daily and notice problems first—the person who already picks up litter on their morning dog walk, now with a way to report and track issues officially. **Block Captains & Civic Organizers**: Neighborhood association leaders who need visibility into which passages have active stewards and which remain orphaned, helping them recruit coverage for gaps. **Adjacent Property Owners**: Business owners and homeowners whose buildings border an alley, who want to coordinate beautification without stepping on toes or duplicating effort. **City Service Liaisons**: Municipal workers who receive reports through 311 systems and benefit from having a consistent, located contact for follow-up on alley-specific issues. ## Core Features 1. **Claim an Alley Segment**: Users draw or select a specific stretch on a map (approximately 50-200 feet), name it something memorable ("The Shortcut Behind Mario's"), and register as its volunteer steward with their contact info and walking schedule. 2. **Issue Reporting with Photo & Location**: Stewards submit problems (burnt light, dumped mattress, graffiti, overgrown vegetation, drainage issue) with a photo, GPS pin, and severity rating—each issue gets a unique ID and timestamp. 3. **Route to City Services**: The app matches issue types to relevant city departments using WellSpr.ing's civic services data, showing stewards which number to call or form to submit, pre-populated with the alley's location details. 4. **Free Items for Beautification**: A dedicated feed surfaces free items from the neighborhood (planters, paint, lumber, outdoor furniture) that stewards can claim for alley improvement projects. 5. **Stewardship Map Dashboard**: A public view showing all adopted segments (green), orphaned segments (gray), and segments with active issues (amber/red)—block captains can filter by status and export contact lists. 6. **Steward Recognition Feed**: When issues get resolved, stewards can mark them complete and share before/after photos; monthly "guardian stats" show total issues resolved, items salvaged, and walks logged. 7. **Neighbor Notification Opt-In**: Residents who don't want to steward can still subscribe to updates about specific alleys they use, receiving alerts when issues are reported or beautification projects need volunteers. ## WellSpr.ing Integration Points ### MCP Tools (via POST https://wellspr.ing/mcp, JSON-RPC 2.0) | Tool | Usage | |------|-------| | `get_city_services` | Fetch list of relevant city departments (streets, sanitation, lighting, code enforcement) to route issue reports correctly | | `search_civic_services` | Query for specific service matches when steward describes an issue—"who handles abandoned vehicles?" | | `get_free_items` | Power the beautification feed, filtered by categories useful for alley projects (outdoor, gardening, building materials) | | `get_local_news` | Surface relevant neighborhood news on the dashboard—street closures, city clean-up days, lighting upgrade announcements | | `get_businesses` | Identify businesses adjacent to alley segments who might want to coordinate on stewardship or sponsor improvements | | `get_business_detail` | Pull contact info for adjacent businesses when stewards want to notify neighbors of issues or projects | | `ask_ody` | Natural language help for stewards: "What's the right department for a pothole in an alley?" or "How do I report illegal dumping?" | | `reach_number` | Get appropriate contact numbers for city services when routing issues | | `get_civic_ideas` | Show stewards what other civic projects exist in their area, potential collaboration opportunities | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/officials` | Display relevant elected officials for the area—useful when systemic issues need escalation beyond 311 | | `GET /api/geo/portals?area_code=NNN` | Fetch neighborhood boundary data to organize alley segments by area and generate block captain views | ### Future Capabilities (Not Yet Live) - **Roadmap: Merchant sponsorship registry** — Would allow businesses to formally sponsor alley segments with small maintenance budgets - **Roadmap: Volunteer hour tracking integration** — Would connect steward activity to community service verification systems - **Roadmap: City 311 API write-back** — Would allow direct submission to municipal systems rather than routing stewards to forms ## Data Model ### `alley_segments` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | name | string | Human-friendly name ("Shortcut Behind Mario's") | | geometry | geojson | LineString or Polygon of segment bounds | | area_code | string | For geo/portal lookup | | status | enum | 'orphaned', 'adopted', 'needs_attention' | | created_at | timestamp | | ### `stewards` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | segment_id | uuid | FK to alley_segments | | name | string | | | contact_method | string | Email or phone, steward's choice | | walk_schedule | string | "Daily mornings" / "Weekends" / etc. | | started_at | timestamp | | | is_primary | boolean | Multiple stewards allowed, one primary | ### `issues` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | segment_id | uuid | FK to alley_segments | | reported_by | uuid | FK to stewards | | type | enum | 'lighting', 'dumping', 'vegetation', 'drainage', 'safety', 'other' | | description | text | | | photo_url | string | | | location_pin | point | Precise GPS within segment | | severity | enum | 'low', 'medium', 'high', 'urgent' | | status | enum | 'open', 'reported_to_city', 'in_progress', 'resolved' | | resolved_photo_url | string | Nullable, for before/after | | created_at | timestamp | | | resolved_at | timestamp | Nullable | ### `subscribers` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | segment_id | uuid | FK to alley_segments | | contact | string | Email for notifications | | notify_on | array | ['new_issue', 'resolution', 'beautification_project'] | ### `beautification_claims` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | segment_id | uuid | FK to alley_segments | | free_item_id | string | ID from WellSpr.ing get_free_items | | claimed_by | uuid | FK to stewards | | status | enum | 'interested', 'picked_up', 'installed' | | installed_photo_url | string | Nullable |