Introducción a la Arquitectura de Software

La arquitectura de software es el conjunto de decisiones estructurales que determinan cómo se organiza un sistema: qué componentes lo forman, cómo se comunican entre sí, qué responsabilidades tiene cada parte y qué restricciones gobiernan su evolución. Estas decisiones son las más costosas de revertir y las que mayor impacto tienen sobre la mantenibilidad, escalabilidad y testabilidad del sistema a lo largo del tiempo.

En GM Transport se trabaja con un stack distribuido: servicios backend en Go y NestJS, APIs en Python FastAPI, aplicaciones móviles en Flutter/Dart y frontends en React y Astro. La heterogeneidad del stack hace indispensable una base arquitectónica coherente que permita a equipos distintos trabajar sobre el mismo sistema con las mismas convenciones.

Por qué importa la arquitectura

Una arquitectura deficiente produce sistemas que funcionan correctamente durante los primeros meses pero que se vuelven progresivamente más difíciles de modificar. Los síntomas más comunes son: cambiar una funcionalidad rompe otra sin relación aparente, los tests son imposibles de escribir sin levantar toda la infraestructura, incorporar un desarrollador nuevo toma semanas y ningún miembro del equipo entiende el sistema completo.

La arquitectura no es un documento que se escribe al inicio del proyecto y se archiva. Es una serie de decisiones activas que evolucionan con el sistema y que el equipo defiende cotidianamente a través de revisiones de código, convenciones acordadas y verificaciones automatizadas.

Paradigmas centrales en GM Transport

Los dos paradigmas que guían el diseño de sistemas en GM Transport son Domain-Driven Design y Arquitectura Hexagonal. No son independientes: se complementan de forma natural.

Domain-Driven Design (DDD) organiza el código alrededor del dominio de negocio. El código debe hablar el mismo lenguaje que los expertos del negocio. Las entidades, servicios y repositorios del dominio reflejan conceptos reales —una Solicitud, una Conciliacion, una Empresa— en lugar de conceptos técnicos —un DAO, un Manager, un Helper. El dominio es el núcleo del sistema y no depende de ninguna tecnología específica.

Arquitectura Hexagonal (Ports & Adapters) garantiza que el dominio sea independiente de la infraestructura. El dominio define puertos (interfaces); la infraestructura implementa adaptadores concretos (GORM, gRPC, HTTP, Azure). Esta separación hace que el dominio sea completamente testeable sin base de datos, sin HTTP y sin servicios externos.

La combinación de ambos paradigmas es visible en GM Fiscal Backend (Go), y es el estándar que se extiende al resto del stack.

La regla de dependencias

El principio más importante de la arquitectura en GM Transport es que las dependencias apuntan siempre hacia el dominio, nunca hacia afuera:

Dominio        ← no depende de nada externo
  ↑
Aplicación     ← depende solo del dominio (interfaces)
  ↑
Infraestructura ← depende del dominio + aplicación + librerías externas
  ↑
Presentación   ← depende de aplicación + dominio/shared

Esta regla aplica independientemente del lenguaje: Go, TypeScript (NestJS), Python (FastAPI) o Dart (Flutter).

Niveles de decisión arquitectónica

Las decisiones arquitectónicas ocurren en tres niveles que se complementan:

Nivel	Alcance	Ejemplos
Sistema	Cómo se distribuyen los servicios y cómo se comunican	Microservicios vs monolito, gRPC vs REST, event-driven
Aplicación	Cómo se organiza el código de un servicio individual	Hexagonal DDD, Clean Architecture, VIPER
Componente	Cómo se implementa una unidad de funcionalidad	Patrones GoF, SOLID, composición vs herencia

Una decisión incorrecta a nivel de sistema es muy costosa de revertir. Una decisión incorrecta a nivel de componente es barata. La arquitectura buena aplica el rigor correcto en cada nivel.

Atributos de calidad

Los atributos de calidad son las propiedades no funcionales que la arquitectura debe garantizar. No son opcionales: son restricciones de diseño que deben evaluarse en cada decisión arquitectónica.

Atributo	Pregunta que responde
Testabilidad	¿Se puede verificar el comportamiento sin infraestructura real?
Mantenibilidad	¿Se puede modificar una parte sin romper el resto?
Escalabilidad	¿Puede el sistema soportar más carga con cambios mínimos?
Observabilidad	¿Se puede entender qué hace el sistema en producción?
Seguridad	¿Están los límites de confianza claramente definidos?
Portabilidad	¿Puede el dominio ejecutarse en otra infraestructura?

Arquitecturas documentadas en esta sección

Esta sección cubre los tipos y patrones de arquitectura utilizados en GM Transport:

• Monolítica: punto de partida comprensible para sistemas pequeños o prototipos.
• Orientada a servicios: el estándar actual de GM Transport para sistemas de producción.
• Orientada a eventos: para flujos asíncronos de alta escala.
• Orientada a recursos: REST como contrato estable entre servicios.
• Hexagonal (Ports & Adapters): el estándar de organización interna de cada servicio.
• Domain-Driven Design: el lenguaje y la estructura que organiza el código alrededor del negocio.

Resumen

• La arquitectura es el conjunto de decisiones estructurales más costosas de revertir. Requiere atención activa, no un documento archivado.
• En GM Transport los dos paradigmas centrales son DDD y Arquitectura Hexagonal, aplicados en conjunto.
• La regla de dependencias es absoluta: el dominio nunca depende de infraestructura.
• Las decisiones ocurren en tres niveles: sistema, aplicación y componente. El rigor debe ser proporcional al costo de revertirlas.
• Los atributos de calidad —testabilidad, mantenibilidad, escalabilidad— son restricciones de diseño, no aspiraciones opcionales.