Última modificación: 2023-11-13

1. Lineamientos de modelado de solución

En Elun, uno de los ejes centrales antes de poder construir piezas de código, es entender cómo, de manera teórica, estas piezas deben funcionar en el contexto del problema o requerimiento, y detectar de manera temprana casos de borde, riesgos operativos y su funcionamiento esperado.

Para ello, se define que para cualquier proyecto de Elun exista un repositorio enfocado en documentar el diseño de software. Estos repositorios deben ser llamados con el nombre del proyecto seguido del sufijo -model

Por ejemplo:

cge-model

notros-model

caja18-model

Dentro de su estructura de carpeta se debe considerar:

.
├── README.html
├── run_structurizr_local.sh
├── docker-compose.yml
├── backend
│   ├── BACKEND.html
│   ├── c4
│   ├── docs
│   ├── database
│   └── sequence_diagrams
└── mobile
    ├── MOBILE.html
    ├── docs
    ├── database
    └── sequence_diagrams

• README.html: Documento que introduce el repositorio del proyecto, explicando de manera general el alcance del proyecto, principales funcionalidades y la misma estructura de carpetas del repositorio (*) (**)

• run_structurizr_local.sh: Script de ejecución para levantar el cliente lite de Structurizr. Este Script está referenciado en el repositorio template.

• docker-compose.yml: Archivo docker compose para levantar instancia de Structurizr Lite.

• backend: Esta carpeta agrupa las definiciones del lado del Backend.

  • BACKEND.html: Este documento describe de manera general el contenido del backend del proyecto. (*) (**)
  • c4: Esta carpeta almacena el modelado del sistema en formato C4 Model. La herramienta que se debe utilizar es Structurizr que será comentada más adelante. .
  • docs: Esta carpeta debe contener todos los documentos de referencia utilizados para el modelamiento. Por ejemplo: Documentos de clientes, fotografías de pizarra, minutas de reuniones relacionadas con el modelamiento. No se debe usar esta carpeta para la gestión del proyecto per se, sino sólo para almacenar documentos útiles para el modelamiento.
  • entities: Esta carpeta debe contener el modelamiento relacionado con modelos de datos o diagrama de clases y entidades. Estos pueden ser generados en PlantUML a través de diagramas de Entidad Relación o diagrama de Clases.
  • sequence_diagrams: Esta carpeta debe contener los diagramas de Secuencia que engloban la solución de los distintos requerimientos y casos de uso.

• mobile: Esta carpeta agrupa las definiciones del lado de la aplicación móvil (si existe en el proyecto). Su contenido debe ser similar a la del backend según aplique.

  (*) Se solicita siempre ser lo más explícito y repetitivo considerando que al lector se le presenta por primera vez el contexto. Se debe llegar a un equilibrio en mantener informado al los implicados del proyecto pero del contenido que sea realmente relevante.

  (**) La forma, prosa y/o estilo de redacción de los documentos puede ser propuesto por el proveedor pero siempre validado por el área de TI de Elun.

Esta estructura no es excluyente si se quieren considerar otros tipos de diagramas, por ejemplo, diagramas de máquina de estado, diagramas de actividad, mapas mentales o cualquier otro diagrama UML, Siempre y cuando tengan relación con el software construido, y puedan ser comprendidos de manera fácil, simple y eficaz.

Diagram as Code

En Elun se prefiere la implementación de modelos de software en lenguajes Diagram as Code por sobre herramientas de diagramación como por ejemplo draw.io, scalidraw.

Structurirz

Structurirz es una alternativa DaC para C4 Model. Actualmente se utilizar una imagen pública correspondiente a Structurizr-Lite que permite levantar de manera local el motor de renderización.

docker-compose.yml

version: '3.8'

services:
  structurizer-lite:
    image: "structurizr/lite:latest"
    container_name: "structurizer-lite"
    ports:
      - "9000:8080"
    volumes:
      - ./backend/c4:/usr/local/structurizr

Dado que los archivos docker-compose referencian al tag latest, es muy probable que mes a mes se vayan encontrando mejoras en Structurizr-Lite. Su equipo es muy activo y constantemente van publicando mejoras. En caso de que una nueva versión latest genere conflictos, basta con fijar una versión estable específica y comentar el porqué se fija dicha versión.

PlantUML

PlantUML es una poderosa implementación de IaC para UML. Siempre está en constante actualización y dispone de una extensión específica para VisualCode.