LeadFlow — Documentación Técnica

SaaS B2B de automatización de prospección comercial · Monorepo TypeScript · 8 desarrolladores

📅 Actualizado: 2026-06-18 🔧 Stack: Next.js · Express · PostgreSQL · Redis 📦 Paquetes: 2 apps · 3 packages · 3 services 🤖 Generado con: actualizador-documentacion-mapas-codigo

Módulos documentados

apps + packages + services

Codemaps generados

frontend / backend / db / int / workers / index

Servicios nuevos

enrichment · email-tracker · scheduler

Onboarding estimado

antes eran 2 semanas

🗺️

Arquitectura del Monorepo

docs/CODEMAPS/INDEX.md · 2026-06-18

CAPA DE PRESENTACIÓN

apps/web (Next.js 14)

↕

packages/ui

packages/types

packages/utils

CAPA DE API

apps/api (Express)

→

services/enrichment

→

services/email-tracker

→

services/scheduler

CAPA DE DATOS

PostgreSQL (Prisma ORM)

Redis (BullMQ queues)

SendGrid · Stripe

📄 docs/CODEMAPS/INDEX.md (estructura generada)

# LeadFlow — Codemap Index
**Last Updated:** 2026-06-18  |  **Generated by:** actualizador-documentacion-mapas-codigo

## Áreas documentadas

| Área         | Archivo           | Módulos | Última revisión |
|---|---|---|---|
| Frontend     | frontend.md       | 6       | 2026-06-18      |
| Backend/API  | backend.md        | 8       | 2026-06-18      |
| Base datos   | database.md       | 5       | 2026-06-18      |
| Integraciones| integrations.md   | 4       | 2026-06-18      |
| Workers      | workers.md        | 3       | 2026-06-18      |

## Cambios desde última versión
- NUEVO: services/enrichment  (microservicio enriquecimiento de leads)
- NUEVO: services/email-tracker (tracking apertura de emails)
- NUEVO: services/scheduler (cron jobs y campañas automáticas)
- ACTUALIZADO: Frontend migrado a React Query + Zustand (eliminado Redux)
- ACTUALIZADO: README.md raíz (arquitectura monolítica → microservicios)

⚛️

Frontend Codemap

docs/CODEMAPS/frontend.md · 2026-06-18

ℹ️ Migración detectada: El frontend fue migrado de Redux Toolkit a Zustand + React Query. La documentación anterior ha sido reemplazada. Todos los módulos reflejan el estado actual del código.

Módulo	Propósito	Exports clave	Dependencias
apps/web/app/	App Router Next.js, layouts y rutas	RootLayout, DashboardLayout	packages/ui
features/leads/	Vista y tabla de leads prospectados	LeadsTable, LeadFilters	useLeadsQuery, packages/types
features/campaigns/	Gestión de campañas de email	CampaignBuilder, StepEditor	useSchedulerMutation, packages/ui
store/	Estado global con Zustand	useAuthStore, useUIStore	zustand 4.x
lib/api/	Queries React Query hacia API	useLeadsQuery, useCampaignMutation	@tanstack/react-query 5.x
packages/ui/	Design system compartido (Button, Modal, Table…)	37 componentes exportados	Radix UI, Tailwind CSS

Flujo de datos — Usuario

Usuario

→

App Router

→

Feature Component

→

React Query

→

apps/api

→

PostgreSQL

🔧

Backend / API Codemap

docs/CODEMAPS/backend.md · 2026-06-18

Módulo	Propósito	Exports / Rutas	Dependencias
apps/api/routes/	Rutas REST Express	GET /leads, POST /campaigns, GET /analytics	express 4.x, zod
apps/api/services/	Lógica de negocio	LeadService, CampaignService, BillingService	prisma-client, stripe-node
apps/api/middleware/	Auth, rate-limit, logging	authMiddleware, rateLimiter	jsonwebtoken, express-rate-limit
services/enrichment/	Enriquecimiento de leads vía APIs externas	POST /enrich, EnrichmentWorker	clearbit, hunter.io SDK, BullMQ
services/email-tracker/	Píxel 1x1 + webhook apertura/click	GET /pixel/:id, POST /click	fastify 4.x, Redis
services/scheduler/	Cron jobs para envíos en horario óptimo	SchedulerService, CampaignCronJob	BullMQ, node-cron, SendGrid

🗄️

Database Codemap

docs/CODEMAPS/database.md · 2026-06-18

📄 Prisma schema — modelos principales (generado desde prisma/schema.prisma)

model Lead {
  id           String      @id @default(cuid())
  email        String      @unique
  company      String?
  status       LeadStatus  // PROSPECTING | ENRICHED | IN_CAMPAIGN | CONVERTED
  enrichedAt   DateTime?
  campaigns    Campaign[]
  trackingEvents TrackingEvent[]
  createdAt    DateTime    @default(now())
}

model Campaign {
  id           String      @id @default(cuid())
  name         String
  steps        CampaignStep[]
  leads        Lead[]
  scheduledJobs ScheduledJob[]
  status       CampaignStatus
}

model TrackingEvent {
  id        String   @id @default(cuid())
  leadId    String
  type      String   // OPEN | CLICK | REPLY
  emailId   String
  timestamp DateTime @default(now())
  lead      Lead     @relation(fields: [leadId], references: [id])
}

🔌

Integrations Codemap

docs/CODEMAPS/integrations.md · 2026-06-18

Servicio	Propósito	Módulo consumidor	Clave env requerida
SendGrid	Envío transaccional y campañas de email	services/scheduler	SENDGRID_API_KEY
Stripe	Suscripciones y billing	apps/api/services/BillingService	STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
Clearbit	Enriquecimiento de leads (empresa, cargo)	services/enrichment	CLEARBIT_API_KEY
Hunter.io	Verificación y búsqueda de emails	services/enrichment	HUNTER_API_KEY

⚙️

Workers Codemap

docs/CODEMAPS/workers.md · 2026-06-18

Worker	Trigger	Queue (BullMQ)	Cola Redis
EnrichmentWorker	Lead creado → enqueue automático	enrichment-queue	bull:enrichment
CampaignSendWorker	Cron schedule + manual trigger	campaign-send-queue	bull:campaign
TrackingFlushWorker	Cada 5 min — flush Redis → Postgres	tracking-flush-queue	bull:tracking

✅ Los 3 workers nuevos (enrichment, campaign-send, tracking-flush) están ahora completamente documentados. Antes no aparecían en ningún README ni guía de arquitectura.

📋

README.md actualizado (raíz del repo)

Reemplaza arquitectura monolítica → microservicios

📄 README.md — sección Architecture (generada)

# LeadFlow

SaaS B2B de automatización de prospección comercial para equipos de ventas.
Stack: TypeScript · Next.js 14 · Express · PostgreSQL · Redis · BullMQ

## Architecture

Este repositorio es un **monorepo** (Turborepo) con la siguiente estructura:

```
leadflow/
├── apps/
│   ├── web/        # Next.js 14 frontend (Zustand + React Query)
│   └── api/        # Express REST API principal
├── packages/
│   ├── ui/         # Design system (Radix UI + Tailwind)
│   ├── types/      # Tipos TypeScript compartidos
│   └── utils/      # Utilidades comunes
├── services/       # Microservicios independientes
│   ├── enrichment/ # Enriquecimiento de leads (Clearbit + Hunter)
│   ├── email-tracker/ # Tracking apertura/click de emails
│   └── scheduler/  # Cron jobs y campañas automáticas
└── docs/CODEMAPS/  # Mapas de arquitectura (generados automáticamente)
```

## Quick Start

```bash
pnpm install                  # instalar deps del monorepo
cp .env.example .env.local    # configurar variables de entorno
pnpm db:migrate               # aplicar migraciones Prisma
pnpm dev                      # lanzar apps/web + apps/api en paralelo
```

→ Ver docs/CODEMAPS/INDEX.md para el mapa completo de arquitectura.

✅

Quality Checklist

✔ Codemaps generados a partir del código real (no escritos a mano)
✔ Todos los file paths verificados — ningún módulo fantasma
✔ Ejemplos de código válidos (compilan con npx tsc --noEmit)
✔ Freshness timestamps en todos los codemaps (2026-06-18)
✔ 3 servicios nuevos documentados por primera vez
✔ Referencias obsoletas eliminadas (Redux, arquitectura monolítica)
✔ Dependencias externas (Clearbit, Hunter, SendGrid, Stripe) trazadas
✔ Workers BullMQ documentados con queues y triggers

⚠️ Pendiente (opcional): Generar grafo visual de dependencias con npx madge --image graph.svg src/ e incluirlo en frontend.md y backend.md.