lead-scraper/BRIEF.md

Lead Gen Scraper — Google Maps

Concepto

Aplicación web que scrapea datos de Google Maps usando la API de Apify. Permite buscar negocios por keyword, ciudad y estado/provincia, mostrando resultados en tabla con panel de detalle.

Stack (adaptado a nuestro entorno)

• Backend: Node.js + Express
• Templates: EJS
• Estilos: Tailwind CSS via CDN (no build step)
• Scraping: apify-client NPM con actor compass/crawler-google-places
• Database: JSON file-backed store (portable, sin dependencia Replit)
• Deploy: VPS (systemd, como el resto de proyectos)

Funcionalidades

Core

1. Búsqueda — Formulario con keyword, ciudad, estado, max resultados
2. Resultados — Tabla con nombre, teléfono, email, web, reviews + panel detalle slide-in
3. Historial — Búsquedas guardadas, ordenadas por fecha, con acciones View/Delete
4. Leads — Bookmark de negocios, página dedicada con gestión completa

UI

• Sidebar fija oscura (dark olive #1a1f1e + green accent #4a7c59)
• Filter bar horizontal superior
• Click en fila → panel detalle deslizante derecha
• Loading states (Apify tarda 30-120s)
• Empty states para todas las páginas
• Error handling con mensajes claros

Gestión de Leads

• Bookmark toggle (save/unsave) desde tabla y panel
• Sync bidireccional tabla↔panel
• Remove from Leads con actualización en vivo
• Persistencia en JSON local

Detalles técnicos

• Server timeout 5 min (búsquedas largas)
• Formato búsqueda: "{keyword} in {city}, {state}"
• Keys: search:{timestamp}, lead:{timestamp}
• dotenv para API token
• .gitignore: node_modules, .env, data/, .DS_Store

Adaptaciones vs briefing original

• ❌ Replit Database → ✅ JSON file store (siempre)
• ❌ Replit deploy → ✅ VPS systemd
• ❌ Replit Secrets → ✅ .env file
• Se mantiene opción de empaquetado zip para portabilidad

Notas

• Apify Actor ID: nwua9Gu5YrADL7ZDj
• El usuario necesitará su propio API token de Apify
• Puerto: 8086 (siguiente disponible en VPS)