Monorepo vs Multi-Repo: Arquitectura de Repositorios

La decisión que nadie documenta bien

Cuando empiezas a construir un producto de marketing digital, la pregunta de cómo organizar tu código aparece antes de lo que imaginas. Y casi siempre se responde por inercia: "usamos lo que ya conocemos". La arquitectura de repositorios —monorepo o multi-repo— define cómo tu equipo colabora, cómo despliegas, y cuánta deuda técnica acumulas en los próximos 18 meses.

Esta es la decisión que tomamos para NEXOR y el razonamiento detrás de ella.

Qué es un monorepo y qué no es

Un monorepo es un repositorio de control de versiones que alberga el código de múltiples proyectos o servicios dentro de una misma estructura. No es un monolito: puedes tener microservicios perfectamente desacoplados y aun así compartir el mismo repositorio. La confusión entre ambos conceptos lleva a muchas decisiones equivocadas.

En contraste, un esquema multi-repo separa cada servicio, librería o aplicación en su propio repositorio independiente. Cada uno tiene su pipeline de CI/CD, su propio historial de commits y su propio ciclo de versiones.

Monorepo no significa código acoplado. Significa que el historial, las herramientas y los cambios transversales viven en un solo lugar.

La diferencia fundamental no es técnica, es organizacional: ¿quién necesita saber qué cambió, cuándo y por qué?

La arquitectura de repositorios y su impacto en productos de marketing

Los productos de marketing tienen una particularidad que los diferencia de un SaaS B2B genérico: el código cambia rápido y de forma transversal. Una nueva integración con Meta Ads toca el pipeline de datos, el dashboard de métricas, los webhooks del CRM y los reportes automatizados. Todo al mismo tiempo.

Ese patrón de cambio transversal es exactamente donde el monorepo brilla. Según análisis publicados por equipos de ingeniería de empresas como Google y Meta —que llevan más de una década operando monorepos a escala masiva—, la reducción de fricción en cambios que afectan múltiples sistemas es el beneficio más consistentemente reportado.

Para un equipo pequeño construyendo un producto de marketing, la lección práctica es esta: si tu backlog tiene tickets que siempre afectan más de un servicio, probablemente un monorepo te ahorra tiempo. Si tus tickets son casi siempre autocontenidos por servicio, multi-repo funciona bien.

Puedes explorar cómo estructuramos nuestras integraciones de datos en el Dashboard CRM de ventas de NEXOR, que centraliza métricas de múltiples canales en una sola vista — un reflejo directo de esta decisión de arquitectura.

Cómo migrar de multi-repo a monorepo sin morir en el intento

Si ya tienes varios repositorios y quieres consolidarlos, la migración no requiere parar el mundo. El proceso gradual funciona mejor que el big bang.

Paso 1: Identifica el código verdaderamente compartido

Antes de mover nada, mapea qué código se copia entre repositorios o qué paquetes internos existen solo para ser consumidos por tus propios servicios. Eso es lo primero que entra al monorepo como paquetes bajo packages/.

Paso 2: Importa repositorios preservando el historial

Con git filter-repo o git subtree puedes mover el historial de cada repositorio al monorepo sin perder los commits. Preservar el historial no es vanidad: es trazabilidad cuando algo falla en producción.

Paso 3: Configura CI/CD con ejecución selectiva desde el primer día

El error más común al migrar es configurar CI que ejecuta todos los tests en cada push. Con Turborepo o Nx, puedes limitar la ejecución a los paquetes afectados por el diff. Esto mantiene los tiempos de CI razonables aunque el repositorio crezca.

Recursos como el HubSpot Engineering Blog documentan patrones similares de migración de infraestructura en equipos de producto a escala mediana.

Paso 4: Establece convenciones de ownership antes de migrar

Un CODEOWNERS bien configurado resuelve el problema de "el monorepo es de todos y de nadie". Define qué equipo o persona es responsible de cada directorio antes de fusionar los repos, no después.

Monorepo en la práctica: lo que nadie te cuenta

Llevar un monorepo en producción tiene fricciones reales que los posts de evangelización suelen omitir. Es honesto nombrarlas.

El onboarding es más pesado inicialmente. Un desarrollador nuevo tiene que clonar un repositorio más grande y entender la convención de workspaces. Con buena documentación se resuelve, pero existe el costo.

Los conflictos de merge en archivos compartidos son más frecuentes. Si diez personas tocan package.json raíz en la misma semana, hay conflictos. La solución es disciplina de branching y lockfiles versionados.

La búsqueda en el IDE se vuelve ruidosa. Buscar una función en un repositorio con 200,000 líneas de código es diferente a buscarlo en uno con 5,000. Herramientas como GitHub Code Search o la búsqueda semántica de Sourcegraph mitigan esto, pero requieren configuración.

Ninguno de estos problemas es bloqueante. Son trade-offs conscientes, no razones para evitar el monorepo.

Sobre cómo los equipos de ingeniería toman estas decisiones de desarrollo de producto, Harvard Business Review ha documentado que la claridad en la estructura de ownership técnico reduce el tiempo de toma de decisiones en equipos de tecnología.

Qué aprendimos después de un año con monorepo

Después de operar NEXOR como monorepo durante más de un año, los beneficios que más valoramos no son los que esperábamos al principio.

El más importante: la visibilidad transversal de cambios. Cuando un desarrollador modifica la forma en que procesamos un lead desde una campaña de ads, el PR muestra exactamente qué otras partes del sistema se ven afectadas. Eso no tiene precio en un producto donde la IA transforma constantemente cómo interactuamos con los datos de marketing.

El segundo: la consistencia de dependencias. Antes de consolidar, teníamos versiones distintas de Zod, de date-fns y de nuestras propias utilidades en diferentes partes del sistema. Eso generaba bugs sutiles en producción que tardaban horas en diagnosticar. Con monorepo, hay una sola versión de cada dependencia crítica.

El tercero, inesperado: mejora la cultura de documentación. Cuando todo el código vive en un lugar, los ADRs (Architecture Decision Records) y los READMEs de cada paquete son más fáciles de mantener actualizados. No hay que ir a cinco repositorios diferentes para entender el estado actual del sistema.

Si quieres ver cómo estas decisiones de arquitectura se traducen en un producto funcional, la automatización de ventas con IA de NEXOR es el resultado práctico de tener código bien organizado que puede evolucionar rápido sin romper lo que ya funciona.

Un monorepo no te hace más rápido por arte de magia. Te quita las fricciones de coordinación que te estaban frenando sin que lo notaras.

La organización del código es también una decisión de negocio: cuánto tiempo tarda tu equipo en entregar un feature que toca múltiples sistemas define tu velocidad de iteración. Y en productos de marketing donde las integraciones con plataformas como Meta o Google cambian constantemente, esa velocidad importa. Statista y otras plataformas de datos como Statista documentan consistentemente cómo las empresas de tecnología que itaran más rápido capturan mayor participación de mercado en verticales competitivas.

Preguntas Frecuentes

¿Qué es un monorepo y en qué se diferencia de un monolito?

Un monorepo es un repositorio único que contiene múltiples proyectos o servicios. Un monolito es una arquitectura donde todo el código se ejecuta como una sola unidad. Son conceptos ortogonales: puedes tener microservicios en un monorepo, o un monolito en múltiples repositorios.

¿Cuándo es mejor usar multi-repo en lugar de monorepo?

Multi-repo conviene cuando los equipos tienen ownership completamente separado sin código compartido, cuando los servicios tienen ciclos de release independientes, o cuando los requisitos de compliance exigen control de acceso granular por dominio de negocio.

¿Qué herramientas se usan para gestionar un monorepo de desarrollo de producto?

Las más usadas son Turborepo (recomendada para equipos pequeños y medianos), Nx (para proyectos grandes con muchos equipos), pnpm workspaces para gestión de dependencias, y Changesets para versionado semántico por paquete dentro del mismo repositorio.

¿Cómo afecta la arquitectura de repositorios al CI/CD?

En monorepo, el CI debe ejecutarse de forma selectiva: solo los paquetes afectados por cada cambio. Turborepo y Nx hacen esto automáticamente. En multi-repo, cada repositorio tiene su propio pipeline, lo que facilita el aislamiento pero complica los cambios transversales entre servicios.

¿Es posible migrar de multi-repo a monorepo sin perder el historial de commits?

Sí. Con herramientas como git filter-repo o git subtree puedes importar repositorios existentes preservando todo el historial de commits. Lo importante es configurar el CI con ejecución selectiva desde el primer día para que los tiempos de build no se disparen con el tamaño.