El momento en que un repo ya no alcanza

Hay un punto en el desarrollo de cualquier sistema complejo en el que el repositorio deja de ser un contenedor cómodo y se convierte en un problema de diseño. No es un fallo técnico: es una señal. Una señal de que el sistema ha crecido hasta el punto en que sus partes tienen ciclos de vida distintos, equipos distintos o, simplemente, razones distintas para cambiar.

Agora llegó a ese punto. Lo que empezó como una plataforma de educación cooperativa —un frontend, un backend, algunas integraciones— fue creciendo hasta convertirse en un ecosistema de siete repositorios interdependientes que se despliegan en infraestructuras completamente diferentes: Vercel, Cloud Run de Google, un VPS en Hostinger, DockerHub, npm. Cada pieza tiene su propio ritmo, su propia cadena de CI y sus propias dependencias externas.

La pregunta que emerge de ese crecimiento no es técnica en el sentido estrecho del término. Es una pregunta sobre coordinación: ¿cómo se mantiene la coherencia entre partes que son autónomas por diseño?

Poly-repo como modelo mental

La respuesta que tomé en Agora fue el patrón poly-repo con un workspace de coordinación. No es mono-repo —cada subrepo vive con su propio .git/, sus propios PRs y su propia historia—, pero tampoco son repos completamente aislados flotando sin relación entre sí.

El repo agora-workspace es, en esencia, una declaración de intenciones. No contiene lógica de negocio. No tiene tests propios sobre el producto. Lo que contiene es un mapa: qué existe, dónde vive cada pieza, cómo se despliega, cómo se clona el ecosistema completo en una máquina nueva. Es documentación ejecutable.

Esa distinción importa filosóficamente. Un workspace de coordinación no es el sistema: es el conocimiento sobre el sistema. Y ese conocimiento, cuando se vuelve explícito y versionado, se convierte en algo que puede evolucionar, revisarse y mejorarse de forma independiente.

La estructura como argumento

Mirar el árbol de Agora es leer un argumento sobre separación de responsabilidades:

  • AgoraFront es la interfaz: editor MDX, terminal web, chat con IA, kanban. Se despliega solo en Vercel desde un push a master. No sabe nada de cómo funcionan los workers.
  • AgoraBack es el servicio agéntico de IA: maneja el streaming SSE de modelos de OpenAI, Anthropic, Gemini y DeepSeek sin los límites de timeout que impone Vercel. Vive en Cloud Run, no en el mismo proceso que el frontend.
  • AgoraHub es el coordinador de sesiones: un servidor socket.io que administra contenedores Docker y expone endpoints HTTP para que el agente IA pueda ejecutar comandos reales en workers.
  • AgoraWorker es el entorno de ejecución: un contenedor Docker por workspace que da una terminal Linux real, con un daemon que mantiene los archivos sincronizados contra MinIO y Firestore.
  • ST y Autologic son la capa lógica: un lenguaje ejecutable de lógica formal con once perfiles (proposicional, modal, deóntico, epistémico, temporal, probabilístico) y un formalizador que convierte texto natural en expresiones de ese lenguaje sin usar IA, solo reglas NLP.

Cada repo tiene una razón de ser que no se superpone con los demás. Esa ausencia de superposición no es accidental: es el resultado de tomar en serio la pregunta de qué pertenece a cada capa.

Lo que la coordinación revela sobre los sistemas

Administrar un ecosistema poly-repo enseña algo que los sistemas monolíticos ocultan: que la complejidad no desaparece cuando se centraliza, solo se oculta. Un mono-repo grande da la ilusión de coherencia porque todo está en el mismo lugar, pero las dependencias implícitas siguen ahí, ahora sin fronteras visibles.

El workspace de Agora hace explícitas las fronteras. Cuando alguien nuevo clona el ecosistema, ejecuta nueve comandos git clone uno por uno. Eso es incómodo. También es honesto: le dice al desarrollador exactamente de qué piezas está hecho el sistema antes de que escriba una sola línea de código.

Hay una cita de Fred Brooks que sigue siendo verdad décadas después: la esencia del software no es la complejidad accidental que resolvemos con mejores herramientas, sino la complejidad esencial que viene de modelar problemas del mundo real. La coordinación entre repos es complejidad esencial. No se puede eliminar; solo se puede gestionar con honestidad.

Infraestructura como texto

Otro patrón que emerge de este workspace es la tendencia a hacer que la infraestructura sea legible como texto. Los scripts de despliegue están en carpetas desplieges-prod/. Los servicios systemd están versionados junto al código que ejecutan. El CLAUDE.md en la raíz del workspace centraliza el conocimiento operacional: secretos, comandos diagnóstico, URLs de producción.

Esto tiene una consecuencia práctica obvia: cualquier herramienta que lea texto —incluidos los agentes de IA— puede razonar sobre la infraestructura sin necesidad de un panel de control externo. Pero la consecuencia más profunda es conceptual: cuando la infraestructura existe como texto versionado, el sistema se vuelve argumentable. Se puede discutir, cuestionar, mejorar. No es un estado opaco mantenido por convención o memoria.

En Agora, el costo estimado de toda la infraestructura en producción es menor a un dólar por mes. Cuarenta y tres contenedores Docker corriendo en un servidor propio, un servicio de IA en Cloud Run que parte de cero instancias, un frontend en Vercel. Ese número no es el punto central, pero revela algo sobre las decisiones de diseño: cuando se entiende bien qué hace cada pieza y dónde debe vivir, no se necesita sobreaprovisionamiento.

La pregunta que queda abierta

Lo que no resuelve un workspace de coordinación —y esto es importante decirlo— es la sincronía semántica entre repos. Que cada subrepo tenga su propio ciclo de vida significa que pueden diverger en convenciones, en versiones de dependencias, en supuestos sobre la interfaz que comparten. Esa es una deuda que se paga en revisiones manuales de compatibilidad.

El workspace es un mapa, no un contrato. Define la topología del sistema, no sus invariantes.

Esa tensión entre autonomía y coherencia es, en el fondo, la misma tensión que aparece en cualquier sistema distribuido, en cualquier organización, en cualquier conjunto de ideas que intenta mantenerse unido sin perder su especificidad. La coordinación nunca es gratuita. La pregunta es solo si ese costo se paga de forma visible o invisible.

En Agora, elegí pagarlo de forma visible. El workspace es la prueba de ese pago.