Estructura del archivo Architecture.md para proyectos de software

En proyectos de software, el primer entregable esencial para un arquitecto no es el código ni los diagramas, sino un archivo de texto claro y concreto que explica cómo se comprende el problema desde el inicio. Este documento suele llamarse Architecture.md y representa el fundamento sobre el cual se construirá la solución.

¿Por qué es importante un archivo Architecture.md en proyectos de software?

El propósito principal de este archivo es resumir el contexto del problema y delimitar sus principales restricciones y consideraciones. Ofrece una visión estructurada que ayuda a comprender el reto y a comunicarlo eficazmente al equipo, basando toda decisión técnica en una base común.

¿Cuáles son los puntos clave del contexto y las restricciones de un proyecto?

El ejemplo presentado corresponde a un proyecto para el Banco Interamericano de Desarrollo referente al modelo de factura electrónica de comercio exterior. Al analizar el problema, el archivo detalla:

• Una descripción general apoyada inicialmente por un LLM que recopila documentación relevante, aunque enfatiza la necesidad de sumergirse más allá de este resumen automático.
• Uso de diagramas de secuencia para entender los flujos principales del sistema, diferenciando los casos grandes de exportación e importación y sus interacciones.
• Lectura de requerimientos y cronogramas para identificar posibles entregables separados y restricciones fundamentales como la extensibilidad, flexibilidad y versatilidad.
• Una mención decidida a la importancia de estándares globales, por ejemplo, la tecnología blockchain para la seguridad y modelos de referencia como el OMA, pero sin estar estrictamente atados a ellos.

¿Qué requisitos no funcionales y desafíos técnicos se deben considerar?

El documento destaca la relevancia de identificar requisitos no funcionales desde el inicio:

• Extensibilidad: La solución debe permitir personalización por entidades externas, como aduanas y tributos de diferentes países.
• Flexibilidad: El sistema requiere ser desplegable en infraestructuras tecnológicas variadas.
• Versatilidad y compliance: Adaptabilidad a múltiples tipos de transacciones, documentos y regulaciones legales.
• Seguridad basada en blockchain y W3C: Garantizando seguridad y trazabilidad mediante estándares modernos.
• Eficiencia y armonización: Minimizar redundancias y buscar armonización de datos si es posible, considerando la alternativa de simplificación para reducir la complejidad.
• Otros aspectos críticos como criptografía, privacidad, transferencia de datos en tiempo real, independencia tecnológica y observabilidad.

¿Qué técnicas facilitan la comprensión profunda del problema?

Para una adecuada identificación de necesidades y actores, el arquitecto debe aplicar diversas técnicas de análisis:

• Lectura detallada de los requisitos y términos de referencia.
• Elaboración de diagramas de secuencia y técnicas de event storming para mapear eventos y actores.
• Enumeración de casos de uso, historias de usuario y diálogo continuo con expertos en el dominio (subject matter experts).
• Registro ordenado de datos adquiridos en cada iteración para transformarlos en conocimiento accionable.

¿Cómo influye la identificación de casos de uso y actores en la arquitectura?

El análisis del Banco Interamericano arroja dos grandes conjuntos de casos de uso, especialmente en exportación de bienes, identificando actores clave como personas exportadoras, compañías y administraciones tributarias diversificadas. El descubrimiento iterativo permite ajustar y validar actores y dependencias, adaptando la solución a las necesidades reales y a la evolución del proyecto.

¿Cómo elegir el estilo arquitectónico adecuado en la fase de prototipo?

La solución prototipo, orientada por las restricciones y el contexto, podría tomar forma como monolito modular, event driven o con microservicios, dependiendo de:

• Tamaño del equipo y experiencia.
• Comunicación con stakeholders no técnicos.
• Estados y eventos del modelo de dominio.
• Extensibilidad e integración con sistemas externos.
• Línea de tiempo y complejidad esperada.

Todos los estilos son válidos si el equipo entiende los trade off de cada uno y puede evolucionar la arquitectura conforme cambian los requisitos. ¿Cuáles han sido tus experiencias previas al estructurar entregables de arquitectura? Puedes compartir tus dudas o enfoques aplicados en proyectos similares.