Migrar la gestión de contratos API no es solo una mejora técnica: es una decisión de arquitectura que impacta directamente en la velocidad, coherencia y escalabilidad del sistema. En este caso, el paso de submódulos Git a un repositorio Proto centralizado permitió desacoplar equipos, introducir versionado semántico real y eliminar fricciones operativas. Además, obligó a diseñar una estrategia robusta para manejar módulos Go privados en distintos entornos (local, CI y Docker), evidenciando que la infraestructura de acceso es tan crítica como el código mismo.
Los sistemas no fallan por falta de código, sino por falta de coherencia. Y esa incoherencia suele aparecer en los contratos que conectan todo: las APIs. Durante mucho tiempo, los archivos proto se gestionaban como un detalle más dentro del backend, mientras que el frontend dependía de ellos a través de submódulos Git. En teoría, esto funcionaba. En la práctica, introducía fricción, acoplamiento innecesario y una dependencia constante entre equipos. El problema no era gRPC ni Protocol Buffers.
La migración hacia un reposorio proto centralizado no fue solo un cambio de estructura. Fue una redefinición de cómo versionamos, distribuimos y gobernamos los contratos del sistema. Y en ese proceso, apareció otro problema crítico: cómo hacer que los módulos Go privados funcionen de forma consistente en todos los entornos.
La arquitectura basada en submódulos Git funcionaba mientras el sistema era pequeño. Pero a medida que crecían los servicios y equipos, comenzaron a aparecer síntomas claros de desgaste:
Un contrato API no es un archivo: es un producto. Y como todo producto, necesita versionado explícito, distribución controlada y reglas claras de consumo. Centralizar los archivos proto en un repositorio independiente transforma ese contrato en una fuente de verdad compartida, desacoplada de cualquier implementación específica. Esto permite escalar no solo el sistema, sino también la organización.
Los submódulos Git no fallan por sí mismos. Fallan cuando se usan para resolver un problema que en realidad es de gobernanza de contratos. En este caso, se estaba tratando un sistema distribuido como si fuera un repositorio único.
El problema no era técnico, era de diseño de sistema.
Crear un repositorio proto independiente no solo organiza archivos: redefine el rol del contrato dentro del sistema. Pasa de ser un artefacto interno a una pieza central de la arquitectura.
Esto convierte la API en una plataforma, no en una dependencia.
Automatizar la generación y publicación del código no fue una optimización: fue una forma de asegurar que el sistema se mantenga consistente sin depender de disciplina manual.
El mayor desafío no fue generar código, sino hacerlo accesible de forma segura y consistente en todos los entornos. Aquí es donde la arquitectura técnica se cruza con la gestión de permisos.
Cada entorno es un sistema distinto. Tratar la autenticación como un caso único es lo que rompe la coherencia.
Migrar a un repositorio proto centralizado no es solo una mejora técnica: es una decisión de arquitectura organizacional. Permite desacoplar equipos, hacer explícitas las decisiones de cambio y construir un sistema más predecible. El mayor aprendizaje no estuvo en gRPC ni en Protocol Buffers, sino en entender que los contratos son el punto más sensible del sistema. Si no están bien definidos, versionados y distribuidos, todo lo demás se vuelve frágil. Escalar un sistema no es escribir más código. Es diseñar mejor sus límites.
