ListingKit

Una ficha de propiedad entra. Salen seis piezas de marketing con la marca de la agencia: ficha técnica en PDF, post de Instagram, carrusel, story, email comercial y vídeo vertical.

El dolor que ataca está documentado en docs/research/: una agencia media teclea los mismos datos tres o cuatro veces —CRM, portal, Canva, PDF— y dedica entre dos horas y dos horas y media por propiedad. Y hay trabajo que directamente no se hace: la ficha en PDF «a menudo no existe» y el vídeo es «prácticamente inexistente» salvo que se contrate a alguien de fuera.

No publica por ti. Genera el material y te lo entrega; subirlo es tuyo.

Cómo está montado

Un motor genérico con un vertical enchufado encima. El motor no sabe qué es un piso: recibe una entidad, la proyecta a una vista pública, resuelve bindings, aplica reglas legales y encarga las piezas a los renderizadores. Lo que sabe de inmuebles vive en niches/inmobiliaria/.

lib/engine/          motor: contratos, puertos, orquestación de trabajos
lib/infrastructure/  adaptadores: Playwright, FFmpeg, Prisma, ZIP, IA
niches/inmobiliaria/ el vertical: esquema, textos, plantillas, reglas legales
app/                 interfaz (Next.js App Router) y API
docs/architecture/   la ADR que manda sobre todo lo anterior

La dirección de dependencias es innegociable y hay un test que la vigila fichero a fichero: el nicho depende del motor, nunca al revés. Levantar un vertical nuevo no toca lib/; hay una plantilla de PRP en .specs/templates/.

Decisiones que no son obvias

• La dirección privada no puede salir. No por convención: PublicPropertyView es una proyección por allowlist y es el único tipo que aceptan las plantillas públicas. Un campo nuevo no llega a una pieza hasta que alguien lo añade a propósito. El editor de texto libre, que es la puerta de atrás, tiene su propio guardarraíl.
• Artefactos inmutables. Cada trabajo escribe en su propio directorio, así que regenerar una pieza no cambia lo que descarga un enlace enviado hace semanas. A cambio los ficheros se acumulan: es un intercambio consciente, no un descuido.
• Una versión por trabajo. Si la propiedad cambia a mitad de una generación, las piezas se niegan en vez de entregar un juego con datos de dos momentos.
• La IA reescribe, no inventa. Apagada por defecto. Cuando se activa parte de un texto existente, y la salida se valida: no puede introducir ningún número que no esté en la ficha o en el texto original. Si lo intenta, se descarta entera.
• La importación no crea a ciegas. Lee el XML del CRM (formato Kyero) y produce un informe de qué entraría y qué falta antes de escribir nada. Las fotos se descargan con protección SSRF: se resuelven las IPs y se rechazan las privadas, la de metadatos de la nube y los saltos de redirección sin validar.
• Texto por plantillas como camino principal. Determinista, sin coste y sin inventar. Ver docs/architecture/niche-engine.md.

Poner en marcha

Ninguna cuenta, clave ni servicio de terceros para tenerlo funcionando en local. Hacen falta dos cosas en la máquina, y conviene comprobarlas antes de empezar porque si faltan el fallo aparece tarde y mal:

Requisito	Para qué	Comprobar
Node 22 o superior	todo	node -v
FFmpeg en el PATH	el vídeo vertical y la recompresión de los audios	ffmpeg -version · ffprobe -version

FFmpeg no se instala con npm. En Windows winget install Gyan.FFmpeg, en macOS brew install ffmpeg, en Debian o Ubuntu sudo apt install ffmpeg. Sin él las otras cinco piezas se generan igual: solo falla el vídeo, y con un mensaje que dice exactamente eso.

npm install
npx playwright install chromium   # el navegador que renderiza PDF e imágenes
npx prisma generate               # cliente tipado a partir del schema
npx prisma migrate deploy         # crea prisma/dev.db
npm run db:seed                   # marca y 3 propiedades de demo con fotos reales
cp .env.example .env
npm run dev                       # http://localhost:3000

En desarrollo eso es todo: no hay contraseña y se entra directo al panel.

Para producción hacen falta dos cosas más, y sin ellas la aplicación se niega a funcionar a propósito:

npm run set-password              # imprime la línea APP_PASSWORD_HASH para el .env
npm run build && npm start

• APP_PASSWORD_HASH: sin él responde 503 a todo. Es deliberado — una instalación sin candado en una red es peor que una que no arranca.
• HTTPS: la cookie de sesión va marcada Secure, así que sobre HTTP el navegador no la guarda y no hay manera de entrar. Ponlo detrás de un proxy con TLS.

El nombre visible se cambia por instalación con NEXT_PUBLIC_APP_NAME. La reescritura de texto con IA es opcional y viene apagada: sin AI_TEXT_ENABLED=1 no se llama a ningún servicio externo y el botón ni siquiera aparece — .env.example explica cómo activarla con tu proveedor y tu clave.

Qué NO hace / límites

• No publica por ti. Genera las seis piezas y te las entrega; subirlas a Instagram, al portal o al CRM sigue siendo cosa tuya.
• No inventa datos. Si un campo no está en la ficha, no sale en la pieza — ni la reescritura con IA (cuando está activada) puede introducir un número que no venga de la ficha o del texto original.
• Una instalación = una agencia = una contraseña. No hay gestión de usuarios, roles ni multi-inquilino: eso es otro producto.
• Los artefactos viven en disco local. Con una sola instancia funciona sin más; con varias hace falta almacenamiento compartido (output/) porque una instancia no sirve lo que escribió otra.
• Cuotas por fichero, no acumuladas. Un uso normal no lo nota; un abuso deliberado, sí.
• Lista completa, con nombre y apellidos, en AUDIT.md §6 ("Lo que NO hace").

Comprobaciones

npm test            # 401 unitarios
npm run test:e2e    # 27 end-to-end (desarrollo + build de producción real)

Los E2E no corren en CI a propósito: levantan dos servidores reales y descargan un navegador completo. Pásalos a mano antes de tocar nada que se publique.

Los E2E corren contra dos servidores: uno de desarrollo y un next build && next start de verdad. Existe porque los dos fallos más caros del proyecto pasaron con toda la suite en verde — sólo se manifestaban en un build de producción. Usan sus propias bases de datos: pasar los tests no toca tus datos.

Estado

Instalable en una agencia detrás de HTTPS. Lo que falta, con nombre y apellidos, está en AUDIT.md §6 — incluida la sección «lo que no hace», que es la que evita la conversación incómoda a los tres meses.

AUDIT.md es la auditoría de seguridad del propio proyecto: tres revisiones en paralelo por ejes distintos, más una pasada adversarial con un modelo diferente del que escribió el código, sobre el producto real y no sobre una checklist genérica. Documenta vulnerabilidades que existieron —fotos que filtraban GPS por EXIF sin recodificar, un logo SVG que permitía XSS persistente same-origin, entre otras 14— y cómo se cerró cada una, con test de regresión (tests/security/). Se deja en el repo a propósito: demuestra proceso, no solo lo afirma.

Contacto

Esto es un proyecto personal, abierto bajo MIT para que lo cojas y lo adaptes sin pedir permiso. Si quieres esto mismo montado para tu agencia, con tu marca y tus flujos, o cualquier otra cosa a medida: [email protected]

Más sobre mi trabajo: nestormartinez.dev