# ScrapNap — Comprehensive Technical Specification & Agentic Architecture

## 1. Executive Summary & Value Proposition
ScrapNap is a 100% free, open-source client-side Chrome Extension (Manifest V3) designed for high-volume B2B lead generation, deep contact enrichment, and instantaneous AI sales pitch generation directly from Google Maps. 

By executing extraction locally inside the user's active residential browser session, ScrapNap completely eliminates proxy subscriptions, cloud scraper fees ($50–$300/mo charged by Apify or Outscraper), and external LLM API rate limits.

---

## 2. Core Differentiators & Technical Mechanics

### A. Zero Proxy Costs & Residential Footprint
Traditional lead scrapers run headless Chromium clusters from datacenters (AWS/GCP), triggering immediate Google IP blocks and requiring expensive residential proxy pools. ScrapNap executes directly in the user's browser, blending seamlessly with legitimate user traffic patterns and human-like scroll intervals (800ms–2400ms).

### B. Concentric Suburban Geo-Expansion Engine
Google Maps strictly caps single search viewports to ~120 listing cards. ScrapNap overcomes this limitation through an automated concentric expansion algorithm:
1. When the current viewport's listings are fully parsed, the expansion engine calculates the centroid coordinates `(lat, lng)`.
2. It generates a ring of adjacent geographic boundary coordinates covering surrounding postal codes and suburbs.
3. The scraper pans the map viewport sequentially to each concentric waypoint, collects unique listings, deduplicates by `place_id` and normalized business phone/address, and continues until reaching target volumes (500 to 1,000+ leads).

### C. 0ms On-Device Chrome Gemini Nano AI Studio
Rather than requiring OpenAI or Anthropic API keys and transmitting prospect PII over the internet, ScrapNap utilizes Google Chrome's built-in `window.ai.languageModel` (Gemini Nano).
- **Pitch Angles**: 
  1. *Review Velocity Deficit* (Targeting businesses with high ratings but low review count).
  2. *Digital Infrastructure Gap* (Targeting businesses missing websites or modern responsive UX).
  3. *Shift Bottleneck* (Targeting high-volume weekend operations).
  4. *Direct Value Proposition* (Immediate bespoke ROI).
- **Outreach Personas**: Aggressive Closer, Consultative Partner, Direct Executive, Concise Specialist.
- **Channels**: Email, LinkedIn Direct Message, SMS, Cold Call Script.

### D. Opportunity Urgency Scoring (0–100 pts)
Deterministic heuristic scoring engine evaluates prospects:
- Missing Website / Inactive Domain: `+25 pts`
- Google Rating < 4.3★ or Review Count < 20: `+20 pts`
- Verified Direct Decision-Maker Email: `+20 pts`
- High-Traffic Shift Schedule: `+15 pts`
- Complete Social Profile Footprint: `+10 pts`

---

## 3. Data Schema & Export Specifications

### Lead Entity Data Model
```typescript
interface ScrapNapLead {
  id: string;                      // Unique hash / place_id
  businessName: string;            // Official business name
  category: string;                // Primary Google Maps category / niche
  rating: number;                  // Decimal star rating (e.g. 4.8)
  reviewCount: number;             // Total number of user reviews
  phone: string;                   // Standardized telephone string (E.164)
  websiteUrl?: string;             // Official domain URL
  address: string;                 // Street address
  city: string;                    // City name
  state?: string;                  // State / Province
  postalCode?: string;             // ZIP / Postal code
  directEmails: string[];          // Crawled email addresses
  mxValid: boolean;                // DNS MX record validation status
  socialLinks: {
    linkedin?: string;
    instagram?: string;
    facebook?: string;
    twitter?: string;
  };
  opportunityScore: number;        // Heuristic urgency score (0-100)
  opportunityTag: string;          // Categorized sales gap
  aiPitch: string;                 // Tailored outreach script
  extractedAt: string;             // ISO-8601 timestamp
}
```

### Export Formats
1. **Multi-Column Excel Spreadsheet (`.xlsx`)**: Styled workbook with formatted headers, rating badges, and clickable URL hyperlinks.
2. **Standard CSV (`.csv`)**: RFC-4180 compliant comma-separated file with quoted fields for CRM ingestion (HubSpot, Salesforce, Close, Lemlist).
3. **JSON Webhook Payload**: POST request payload dispatched to Zapier, Make, n8n, or custom REST webhooks.

---

## 4. Unpacked Chrome Extension Installation Guide
1. Download `extension-zip.zip` from GitHub: https://github.com/Abhijith-web-dev/scrapnap-extension/raw/main/extension-zip.zip
2. Extract the archive into a dedicated directory on your local filesystem.
3. Open `chrome://extensions` in Google Chrome, Chromium, Brave, or Microsoft Edge.
4. Enable the **Developer mode** toggle in the top-right corner.
5. Click the **Load unpacked** button in the top-left toolbar.
6. Select the extracted extension directory.
7. Open Google Maps (`https://www.google.com/maps`), search any query (e.g., "HVAC contractors in Dallas"), and launch ScrapNap.

---

## 5. Web Portal & Developer Endpoints
- **Official Portal**: https://scrapnap-dev.web.app/
- **Developer Workspace & API Key Generator**: https://scrapnap-dev.web.app/dashboard
- **Architecture & Install Guide**: https://scrapnap-dev.web.app/docs
- **Product Roadmap**: https://scrapnap-dev.web.app/roadmap
- **Privacy Policy (100% Client-Side Privacy)**: https://scrapnap-dev.web.app/privacy
- **Terms of Service**: https://scrapnap-dev.web.app/terms
- **GitHub Repository**: https://github.com/Abhijith-web-dev/scrapnap-extension
- **Direct ZIP Download**: https://github.com/Abhijith-web-dev/scrapnap-extension/raw/main/extension-zip.zip
- **License**: MIT License (Free for personal and commercial usage)