## Overview

The NeighborBook is a geospatial, community-driven platform for sharing and borrowing books within local neighborhoods. It prioritizes proximity-based discovery, user reciprocity, and community trust, with extensible security and moderation features.

## Core Design Priorities

- **Book Entities:** Books are stored as unique, deduplicated entries.
- **Listings:** Users list books via a relational structure that links users to books with location and availability.
- **Geospatial Indexing:** User and listing locations are geospatially indexed for proximity-based discovery.
- **Search:** Full-text search with fuzzy matching via MongoDB Atlas Search.
- **AI Metadata Processing:** Automated post-ingest metadata cleaning, deduplication, and enhancement using LLM services.
- **Geospatial Filtering:** Listings are displayed within a user-defined radius.
- **Browsing by Category:** Genre-based filtering within the user’s proximity.
- **Real-Time Updates:** The app detects and pushes nearby new listings based on user preferences.
- **User Profiles:** Profiles store preferences, browsing history, favorites, notification settings, and credit scores.
- **Push Notifications:** Real-time alerts for new nearby listings.
- **Background Data Refresh:** Periodic verification of book metadata and user location.

## MVP Feature Set

- Book listings with location tagging
- Geospatial discovery and search filtering
- User authentication via SMS verification
- One-to-one in-app messaging
- Push notifications for relevant new listings
- Basic credit system for soft throttling
- QR code-based trade confirmation
- Guest browsing with anonymized density data

---

## AI Metadata Cleaning Pipeline

### Workflow:

1. **User Submission:**
    - Book details entered or fetched via external APIs (Google Books, Open Library).
2. **AI Post-Ingest Processing:**
    - Clean titles (remove edition/series noise).
    - Normalize author names.
    - Rewrite or summarize descriptions.
    - Detect and merge near-duplicates.
3. **Tools:**
    - OpenAI API (e.g., GPT-4-turbo) for description rewriting and disambiguation.
    - Fuzzy string matching (e.g., Levenshtein distance) and heuristic comparisons across external IDs.

---

## Issue Reporting Pipeline

- In-app reporting system tied to:
    - Book ID
    - Pre-set issue categories (e.g., incorrect metadata, wrong cover)
    - Optional user notes
- Reports logged in a `reports` collection.
- Reports can trigger:
    - Manual moderation queue review
    - Automated re-fetch or AI reprocessing

---

## Push Notification System

| Component | Technology |
| --- | --- |
| Notification Service | Firebase Cloud Messaging |
| Triggering Logic | Backend event detection |
| Subscription Management | MongoDB user profiles |

### Notification Flow:

1. New listing is created.
2. Backend identifies relevant users based on radius and genre preferences.
3. FCM pushes notifications to matching users.

---

## Location Services

| Feature | Technology |
| --- | --- |
| User Geolocation | Mobile GPS with IP fallback |
| Geospatial Indexing | MongoDB 2dsphere indexes |
| Map Visualization | Mapbox SDK or Google Maps SDK (optional) |

---

## Background Services

| Service | Technology | Purpose |
| --- | --- | --- |
| Metadata Refresh | Cron jobs, serverless (e.g. AWS Lambda) | Periodically verify and update metadata |
| Location Sync | App session trigger, optional periodic sync | Maintain current user location |
| AI Processing Queue | Celery, AWS SQS, or equivalent | Background metadata processing |

---

## Backend Services

| Service | Purpose |
| --- | --- |
| Authentication | Firebase Authentication via SMS |
| Geospatial Query Engine | MongoDB 2dsphere queries |
| Push Notifications | Firebase Cloud Messaging |
| AI Processing Queue | GPT API or fine-tuned LLM |
| External Book APIs | Google Books, Open Library |
| User Preferences Engine | Notification and search filtering |

---

## Security & Trust Features

### 1. SMS Verification (Required)

- SMS-based account authentication via Firebase.
- Re-verification required when:
    - Changing home location.
    - Resetting account access.
- Helps prevent fake account farming.

### 2. Government ID Verification (Future Feature)

- Integration with ID verification platforms such as Persona, Onfido, or Stripe Identity.
- Optional or required for expanded account privileges.

### 3. Photo Verification (Future Feature)

- Selfie-based flow for additional account trust.
- Verification required before first trade or at signup for higher-trust users.

### 4. Location Integrity

- Home location can only be changed once every 90 days.
- User browsing radius can change based on current GPS, but trading is restricted to home neighborhood unless reset via time-gated process.

Example Schema:

```json
json
CopyEdit
{
  "home_location": { "type": "Point", "coordinates": [-118.463, 33.990] },
  "home_set_at": "2025-06-16T10:00:00Z"
}

```

### 5. Credit/Trust System

- Community credit score based on books shared vs. books received.
- Formula:

```
text
CopyEdit
credit_score = books_shared / (books_received + 1)

```

### Throttling Tiers:

| Credit Range | Enforcement Method |
| --- | --- |
| 0.5 – 0.7 | Soft nudges via email/in-app |
| 0.3 – 0.5 | Waiting period (e.g. 48 hours) |
| < 0.3 | Payment required to bypass throttling |

### 6. Trusted Meet-Up Spots

- Pre-approved public spaces (e.g., libraries, bookstores, coffee shops).
- Stored in a `trusted_locations` collection:

```json
json
CopyEdit
{
  "_id": "spot123",
  "name": "Venice Public Library",
  "address": "501 S Venice Blvd, Venice, CA",
  "coordinates": [-118.463, 33.990],
  "type": "library"
}

```

- Recommended during in-app messaging for trade meet-ups.
- Optional incentive: faster credit accrual for using trusted locations.

### 7. In-App Messaging

- One-to-one messaging system built with Firebase or Socket.io.
- Features:
    - Flagging and reporting of inappropriate messages.
    - Basic moderation dashboard.
    - Future option for AI-assisted moderation.

### 8. Trade Confirmation

- QR Code Flow (Primary):
    - Each listing generates a unique QR code.
    - Both users scan each other’s code to confirm trade.
    - Automatically triggers feedback prompt.
- Geofencing (Optional Future Layer):
    - Confirm trades via GPS check-in near trusted meet-up spots.

---

## Guest Browsing and Privacy

| Feature | Design Decision |
| --- | --- |
| Mock Data | Pre-seeded listings for initial browsing |
| Real-Time Density Search | Search for active users/listings by zip or address |
| Privacy Protection | Only anonymized density stats shown (e.g., "15 listings nearby") |
| Full Listings View | Requires account signup |

### Example MongoDB Aggregation:

```jsx
javascript
CopyEdit
db.listings.aggregate([
  { $geoNear: {
      near: { type: "Point", coordinates: [lng, lat] },
      distanceField: "distance",
      maxDistance: 5000,
      spherical: true
    }
  },
  { $match: { available: true } },
  { $group: { _id: null, count: { $sum: 1 } } }
])

```

---

## Conclusion

This design document captures the primary architectural components, security mechanisms, and MVP functionalities required to build NeighborBook. The design emphasizes geospatial discovery, community trust, and scalable moderation systems, with extensibility for future features such as photo and ID verification, geofencing, and AI-assisted content review.