NeighborTool Library

Consumer

Original Idea

Neighborhood Tool Library A web app where neighbors can list tools they own, request to borrow from each other, and track loans with a simple reputation system.

Product Requirements Document (PRD): NeighborTool Library

1. Executive Summary

NeighborTool Library is a hyper-local, peer-to-peer (P2P) resource-sharing platform designed to increase the utilization of underused tools and decrease the financial and environmental barriers to home improvement. By combining advanced geospatial indexing, a "Weighted Liquid Rank" reputation system, and secure transaction flows, the platform empowers neighbors to borrow and lend high-quality tools safely within their immediate community.

2. Problem Statement

The average power drill is used for only 13 minutes in its entire lifetime. High ownership costs for specialized tools create financial waste, while the manufacturing of redundant goods increases environmental impact. Additionally, urban dwellers lack the storage space for seasonal tools, yet no secure, trust-based local infrastructure exists to facilitate sharing without significant risk of theft or damage.

3. Goals & Success Metrics

  • Utilization Rate: Achieve a 40% monthly active listing utilization (at least one loan per month).
  • Community Trust: Maintain an average platform trust score of 4.5/5.0 across all users.
  • Geospatial Density: Reach "Critical Mass" (50+ active tools) within a 2-mile radius for 10 initial target neighborhoods.
  • Waste Reduction: Track "CO2 avoided" metrics based on tool manufacturing offsets (Projected 500kg CO2 offset per 100 loans).

4. User Personas

DIY Dave (The Lender)

  • Profile: Homeowner with a well-stocked garage.
  • Need: Wants to offset the cost of his expensive table saw and help neighbors, but fears his tools being stolen or broken.

Minimalist Mia (The Borrower)

  • Profile: Apartment dweller with zero storage space.
  • Need: Needs a ladder for 2 hours to change a smoke detector battery. Doesn't want to buy or rent a truck to visit a commercial tool rental shop.

Sustainable Sam (The Community Advocate)

  • Profile: Urban gardener and environmentalist.
  • Need: Wants to organize a neighborhood "tool swap" day and ensure shared resources are maintained.

5. User Stories

  • As a user, I want to verify my address so that I am only connected with neighbors within a safe distance.
  • As a lender, I want to set a security deposit via Stripe so that I am protected if my tool is damaged.
  • As a borrower, I want to search for tools by proximity using a map so that I don't have to travel far.
  • As a borrower, I want to scan a QR code upon pickup so that the loan period officially begins and my liability is clear.
  • As a lender, I want to see a borrower's "Weighted Liquid Rank" so that I can decide whether to trust them with high-value equipment.

6. Functional Requirements

6.1 User & Neighborhood Management

  • Address Verification: Integration with Google Maps API to verify residential status.
  • Privacy Obfuscation: Automatic mapping of users to Uber H3 (Resolution 8) Hexagons to hide exact house locations.
  • Identity Trust: Mandatory email verification + optional ZK-KYC (Zero-Knowledge) for high-value tool access.

6.2 Tool Inventory

  • Listing Engine: Support for photo uploads (Cloudinary), category tagging, and condition status (New, Good, Well-Used).
  • Availability Calendar: Lenders can block out dates when they need their own tools.

6.3 Transactional Flow

  • Booking System: Request/Approve/Deny workflow with real-time status updates.
  • Security Deposits: Automatic "Manual Capture" hold for rentals <7 days and "SetupIntents" for rentals >10 days.
  • Contactless Handoff: System-generated QR codes (SVG) for both pickup and return verification.

6.4 Reputation System

  • Double-Blind Reviews: Ratings are only revealed once both parties submit or 14 days pass.
  • Weighted Scoring: Reputation scores calculated based on account age, transaction volume, and temporal decay.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend: Next.js v16.1.3 (utilizing Turbopack and the stable React Compiler).
  • Styling: Tailwind CSS v4.1.18 (CSS-First configuration).
  • Runtime: Node.js v24.13.0 (LTS).
  • Database: PostgreSQL 18 with PostGIS 3.6.
  • Authentication: Clerk (integrated with Next.js 16 Server Actions).
  • Real-time/Chat: Supabase Realtime (Presence & Broadcast).
  • Storage: Cloudinary for image optimization.

7.2 Architecture Patterns

  • Geospatial Indexing: Use SP-GiST for low-latency point-in-polygon searches in dense urban areas.
  • Privacy: Implement the 1,750-foot rule (Oregon 2026 standard) for public map displays.
  • Messaging: Real-time coordination using CRDT-based Presence logic to show lender/borrower typing status.

8. Data Model

User

  • id: UUID
  • clerk_id: String (External IDP link)
  • h3_index: String (Resolution 8 Hex ID)
  • reputation_score: Float (0.0 - 5.0)
  • verified_at: Timestamp

Tool

  • id: UUID
  • owner_id: FK -> User
  • category: Enum (Power, Hand, Garden, Automotive)
  • geom: PostGIS Geometry (Point, obfuscated)
  • deposit_amount: Decimal
  • status: Enum (Available, OnLoan, Maintenance)

Loan

  • id: UUID
  • tool_id: FK -> Tool
  • borrower_id: FK -> User
  • status: Enum (Pending, Active, Returned, Disputed)
  • qr_code_hash: String (HMAC-signed)
  • start_date: Timestamp
  • end_date: Timestamp

9. API Specification (Selected Endpoints)

POST /api/tools/search

  • Payload: { lat: float, lng: float, radius_meters: int, category: string }
  • Response: Array<Tool> (Coordinates obfuscated to H3 center).

POST /api/loans/verify-handoff

  • Payload: { loan_id: uuid, qr_token: jwt, type: 'PICKUP' | 'RETURN' }
  • Logic: Verifies signed JWT; triggers Stripe "Manual Capture" if pickup.

GET /api/users/[id]/reputation

  • Response: { score: float, reviews: Array<Review>, weight_factor: float }

10. UI/UX Requirements

  • Map View: A full-screen map using Mapbox/Google Maps, showing clusters of tools within hexagonal bins.
  • Tool Card: High-resolution image, "Trust Badge" (indicating lender's reputation), and "Distance" (e.g., "6 mins away").
  • Mobile-First Pickup UI: Dark-mode optimized scanning interface with a large "Scan QR" button for use in outdoor/bright conditions.
  • Trust indicators: Visualization of "Weighted Liquid Rank" showing how long the user has been a member.

11. Non-Functional Requirements

  • Performance: Search results must return in <50ms using PostgreSQL 18 AIO (Asynchronous I/O).
  • Security: Rate limiting on geospatial queries to prevent "triangulation attacks."
  • Accessibility: WCAG 2.1 Level AA compliance for high-contrast visibility.
  • Privacy: Compliance with 2026 OCPA (Oregon Consumer Privacy Act) for sensitive location data.

12. Out of Scope

  • Peer-to-peer shipping or delivery (Pickup only).
  • Tool sales/marketplace.
  • Professional-grade insurance (handled via user-agreed Stripe deposits for MVP).

13. Risks & Mitigations

  • Risk: Tool Theft/Damage. Mitigation: Stripe security deposits and identity verification.
  • Risk: Privacy/Safety. Mitigation: H3 Hexagonal obfuscation and the 1,750-foot radius rule.
  • Risk: Review Spam. Mitigation: Linguistic Stylometry to detect AI-generated reviews.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize project with Next.js v16.1.3 and Node.js 24.13.0 LTS
  • [ ] Set up Tailwind CSS v4.1.18 with CSS-first configuration
  • [ ] Configure ESLint and Prettier for React 19+ standards
  • [ ] Provision PostgreSQL 18 database with PostGIS 3.6 extension

Phase 2: Identity & Geospatial Core

  • [ ] Integrate Clerk for identity management
  • [ ] Set up Supabase Realtime for database webhooks and Presence
  • [ ] Implement H3 indexing logic for address obfuscation (Resolution 8)
  • [ ] Build SP-GiST indexed search for ST_DWithin performance

Phase 3: Inventory & Management

  • [ ] Build tool listing form with Cloudinary image upload
  • [ ] Implement Tool CRUD with Row Level Security (RLS)
  • [ ] Create calendar-based availability picker for lenders

Phase 4: Lending Workflow & Payments

  • [ ] Integrate Stripe "Manual Capture" flow for security deposits
  • [ ] Build Loan State Machine (Requested -> Approved -> Active -> Completed)
  • [ ] Implement in-app real-time messaging using Supabase Broadcast
  • [ ] Develop QR code generation using react-qr-code (SVG)

Phase 5: Verification & Reputation

  • [ ] Implement QR scanner using html5-qrcode for mobile web
  • [ ] Develop "Weighted Liquid Rank" scoring algorithm (Decay + Volume weighting)
  • [ ] Build Double-Blind review release logic
  • [ ] Implement AI stylometry check for review fraud detection

Phase 6: Launch & Optimization

  • [ ] Optimize PostgreSQL 18 with io_method = io_uring for pre-fetching
  • [ ] Conduct accessibility audit (WCAG 2.1 AA)
  • [ ] Deploy to Vercel (Frontend) and Railway (Managed DB)