Initial commit: Lead Scraper - Google Maps

BRIEF.md

@@ -0,0 +1,52 @@
+# 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)