VavaStone - Inventario, ventas y entrega para la industria de la piedra natural

Desafío

VavaStone es una plataforma internacional de inventario, ventas y entrega de piedra natural — un dominio con logística compleja: existencias en múltiples almacenes, envíos calculados por peso, precios en varias divisas y flujos de trabajo de clientes multinacionales. El equipo de ingeniería estaba distribuido en varios países. Para cuando me incorporé, la arquitectura de microservicios en Go + React era funcional pero había acumulado fricción: los límites entre servicios eran implícitos, el desarrollo local requería una configuración considerable y la incorporación de nuevos ingenieros tomaba demasiado tiempo.

Descubrimiento

Unas semanas de exploración del código y conversaciones con el equipo identificaron tres causas raíz. Primera: los servicios se comunicaban mediante JSON sin tipar y sin esquema compartido, lo que hacía que los errores de integración fueran sutiles y difíciles de detectar antes de producción. Segunda: el entorno local de Kubernetes requería pasos manuales que no estaban documentados, así que cada ingeniero tenía una configuración ligeramente distinta. Tercera: el proceso de contratación e incorporación era informal — el conocimiento vivía en la cabeza de las personas, no en documentación.

Opciones consideradas

1. Introducir un service mesh y clientes autogenerados — demasiado pesado para el tamaño del equipo; habría tomado meses migrar los servicios existentes.
2. Añadir especificaciones OpenAPI y generar clientes tipados por servicio — elegida como el punto medio pragmático. Contratos explícitos, tipos generados, sin nueva infraestructura.
3. Migrar a un monorepo con paquetes de tipos compartidos — aplazada; viable a largo plazo pero demasiado disruptiva a corto plazo.

Decisión

Introducir contratos de API tipados de forma incremental a medida que se tocan los servicios, en lugar de una migración de una sola vez. En paralelo: documentar el entorno de desarrollo local en un script de configuración repetible, y formalizar el proceso de incorporación con una lista de verificación escrita y un compañero designado para los nuevos ingenieros.

Implementación

Añadí definiciones OpenAPI a los servicios en los que trabajé y generé tipos de cliente TypeScript usados por el frontend en React. Esto capturaba una clase de errores en tiempo de compilación que antes solo aparecían en staging. Refactoricé la configuración local de Kubernetes en un flujo de trabajo documentado basado en Makefile — `make dev-up` en lugar de seis comandos manuales. Los nuevos ingenieros podían ejecutar toda la pila localmente desde el primer día.

Del lado del producto, entregué mejoras al módulo de gestión de inventario y pedidos: visualización de niveles de stock entre almacenes, seguimiento de estado de pedidos y flujos de cálculo de coste de envío. Participé activamente en la contratación: escribí descripciones de puesto, realicé entrevistas técnicas y dirigí la primera incorporación estructurada para dos nuevos ingenieros.

Resultado

Los errores de integración entre servicios se redujeron de forma medible, ya que los contratos tipados detectaban discrepancias en tiempo de compilación. El tiempo de adaptación de los nuevos ingenieros se acortó de semanas a días gracias al entorno de desarrollo documentado. El equipo entregó funcionalidades a una velocidad notablemente mayor en los trimestres posteriores a las mejoras de herramientas.

Demo

El video a continuación demuestra el resultado de exigir una alineación estricta de tipos en las llamadas a la API — las discrepancias de tipos aparecen automáticamente como errores de compilación, eliminando toda una categoría de errores de integración en tiempo de ejecución.

Grabación intermedia de I+D explorando la generación de tipos de backend a frontend asistida por IA — un experimento para automatizar el flujo de alineación de tipos que antes se hacía manualmente.

Alfa temprana del prototipo del sistema de reportes — analítica de pedidos e inventario construida sobre la capa de datos con seguridad de tipos.