# Track Migrating Library Books Between Branches ## The Problem Public library systems constantly shuttle books between branches to fulfill holds, but this creates invisible knowledge gaps for patrons. A branch might consistently accumulate excellent graphic novels or overflow cookbooks, but no one shares this intel. Readers wait 2-3 weeks for holds when the book they want might be sitting on a shelf across town—they just don't know which shelf. ## Who Uses It **The Genre Hunter**: A parent who knows the downtown branch always has better kids' graphic novels than the website says, and wants to share that knowledge with other families. **The Serendipity Seeker**: A reader who enjoys browsing physical shelves but wants to maximize their trip by visiting branches with strong collections in their interests. **The Hold Avoider**: Someone who'd rather drive 15 minutes to grab a book today than wait three weeks for a hold to arrive at their nearest branch. **The Library Power User**: A patron who visits multiple branches weekly and notices patterns—this branch gets overflow from the main library, that one accumulates large print books. ## Core Features 1. **Branch Sighting Reports**: Anyone can report "Found [title/genre] at [branch] on [date]" with optional photo of the shelf section. No account required for basic reports; optional account for tracking your contributions. 2. **Genre Heat Map**: Visual map showing which branches tend to accumulate which genres based on crowdsourced sightings. "West Branch: strong in mysteries, cookbooks. East Branch: graphic novels, audiobooks." 3. **Branch Profile Pages**: Each library branch gets a page showing recent sightings, emerging genre strengths, and civic service details pulled from WellSpr.ing (hours, contact, accessibility). 4. **"Alert Me" Subscriptions**: Users can say "Tell me when someone spots gardening books at any branch" and get notified of relevant sightings via email. 5. **Hidden Gem Feed**: Chronological feed of interesting finds—"Spotted: Complete Calvin & Hobbes box set at Riverside Branch" with timestamps and shelf locations. 6. **Branch Comparison Tool**: Select 2-3 branches, see side-by-side genre strengths and recent sighting activity to plan your browsing trip. 7. **Civic Service Quick Links**: Each branch page links to official library contacts and related civic services, helping users report issues or request services directly. ## WellSpr.ing Integration Points ### MCP Tools (via POST to `https://wellspr.ing/mcp` as JSON-RPC 2.0) - **`search_civic_services`**: Query for library branches by location. Returns branch names, addresses, and service details. Use this to populate your branch database and verify branch existence when users submit sightings. - **`get_city_services`**: Retrieve broader library system information—main library contacts, interlibrary loan services, accessibility accommodations. Display on branch pages. - **`ask_ody`**: Let users ask natural language questions like "Which branch usually has the best sci-fi selection?" Ody can synthesize sighting data and civic info into conversational responses. - **`get_civic_ideas`**: Check if other builders have proposed library-related tools or features. Display related civic ideas on your "About" page to encourage ecosystem participation. - **`get_adjacent_nodes`**: When a user is viewing one branch, fetch geographically adjacent community nodes to suggest "Nearby branches you might also check." ### REST Endpoints - **`GET https://wellspr.ing/api/geo/portals?area_code=NNN`**: Fetch geographic portal data for the library's service area. Use this to validate that reported branches fall within the civic geography you're serving. ### Future Capabilities (not yet live) - **Roadmap: Library API Integration** — If your local library system has a public catalog API, a future version could cross-reference sightings with official availability. This would require custom integration work outside WellSpr.ing. - **Roadmap: Covenant Commerce** — Future WellSpr.ing features may support "gratitude tokens" for prolific sighting contributors, but payment rails are not currently available. ## Data Model ### `branches` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | name | string | "Riverside Branch Library" | | address | string | Full address | | civic_service_id | string | Reference from `search_civic_services` | | lat, lng | float | For mapping | | created_at | timestamp | | ### `sightings` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | branch_id | uuid | FK to branches | | genre | string | Controlled vocabulary: "mystery", "cookbook", etc. | | title | string | Optional specific title | | description | text | "Whole shelf of new arrivals" | | photo_url | string | Optional | | reported_by | uuid | FK to users, nullable for anon | | reported_at | timestamp | | ### `users` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | email | string | For alerts | | display_name | string | Public attribution | | created_at | timestamp | | ### `alerts` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | user_id | uuid | FK to users | | genre | string | What they're watching for | | branch_id | uuid | Nullable—null means "any branch" | | active | boolean | | ### `genre_scores` (computed/cached) | Field | Type | Notes | |-------|------|-------| | branch_id | uuid | FK to branches | | genre | string | | | sighting_count | int | Last 90 days | | last_sighting | timestamp | | ## Vibe Coding Prompt to Get Started Paste this into Claude or Replit Agent: ``` Build a civic tech web app called "Library Scouts" for tracking interesting book finds at public library branches. **Tech Stack**: React frontend + Express.js backend on Replit, SQLite database (upgrade to Postgres later), Leaflet.js for maps. **First Milestone**: Core sighting submission flow 1. Create a simple form at /report where anyone can submit: - Branch name (dropdown, start with 5 hardcoded branches) - Genre (dropdown: mystery, sci-fi, cookbook, graphic novel, kids, biography, other) - Optional title - Optional description - Submit button (no auth required) 2. Store sightings in SQLite with timestamp 3. Create a /feed page showing the 20 most recent sightings, newest first, with branch name, genre, and time ago 4. Create a /branches page with a simple card grid showing each branch and its sighting count 5. Add a basic Leaflet map on the homepage showing branch locations as pins (hardcode coordinates for now) **Integration**: Add a backend route GET /api/civic-services that calls the WellSpr.ing MCP endpoint search_civic_services via JSON-RPC 2.0 POST to https://wellspr.ing/mcp looking for "library" services. Display results on the /branches page. **Style**: Clean, friendly UI with a book/library theme. Use Tailwind CSS. Mobile-friendly since people will report from their phones at the library. Start with the sighting submission form and feed. That's the core loop—once people can report and see reports, everything else builds from there. ``` ## Covenant Alignment This project embodies **authentic transactions** (real people sharing real observations,