Documentando nuestros flujos con Mermaid

Dentro de tu equipo ¿soléis documentar los flujos de trabajo de vuestras apps? ¿Te has sentido perdido en algún momento a la hora de entender cómo funcionan? Tranquilo, a todos nos ha pasado y es totalmente normal, cuando nuestra aplicación se hace mas grande suele hacerse más compleja y podemos olvidar alguna interacción interna o externa con otra aplicación. Para solucionar esto, podemos usar alguna herramienta para visualizar esos flujos.

Que es Mermaid

Mermaid es una herramienta, construida con Javascript, que nos permite crear diagramas y grafos a partir de codigo Markdown. Es una herramienta perfecta para completar nuestros README con diagramas de flujo completos y fáciles de editar.

Hablamos de crear flujos, pero con Mermaid tambien podemos crear esquemas de bases de datos, maquinas de estados, esquemas de POO o incluso grafos temporales para gestionar proyectos.

Como usar Mermaid

Para quien haya escrito Markdown, el uso de Mermaid va a ser muy fácil. Para probar, podemos usar el editor que tenemos disponible desde su web.

La primera línea que tenemos que escribir define el tipo de gráfico que vamos a implementar. Si queremos dibujar un diagrama de flujo, tenemos que escribir flowchart TD. También podemos usar diagrama de secuencia, de clases, diagramas de estados o máquinas de estados, Entidad-Relacion, Gantt e incluso grafos de Git. Hay un ejemplo de cada uno en el editor online para que podamos empezar a probar.

Creando nuestro primer ejemplo

Pongamos por ejemplo un caso en el que nuestra aplicación consta de un frontend, donde nuestro usuario va a registrarse, y después va a editar su perfil, añadir una información medica que tendrá que ser validada con otra aplicación externa.

sequenceDiagram
    Frontend->>+Backend: Usuario manda email y contraseña
    Backend->>Frontend: Sesion iniciada, envia token
    Frontend->>Backend: Edita informacion medica
    Backend->>+Aplicacion Medica externa: Envia datos del usuario
    Aplicacion Medica externa->>Backend: Confirma datos
    Backend->>Frontend: Confirma edicion de datos

Como vemos, todo el gráfico lo hemos desarrollado con código Markdown. Para declarar una entidad dentro de este flujo solo tenemos que escribir su nombre, y añadir un + si es la primera vez que enviamos un flujo. No tenemos que preocuparnos de las flechas, Mermaid se encarga de saber hacia dónde tienen que apuntar.

Podemos hacer algo más complejo. Por ejemplo, una aplicación en la que vamos a describir flujos internos usando asincronía o simplemente especificando que la se está produciendo un procesamiento interno con procesos en otros hilos.

sequenceDiagram
    participant b as Banco
    participant m as Microservicio
    participant mobile as App movil
    actor u as Usuario

    u->>mobile: Paga por internet
    mobile->>m: Crea orden de pago
    activate m
    m->>m: Scheduler que comprueba pagos
    deactivate m
    m->>b: Envia datos de pago
    activate b
    b->>b: Realiza pago
    b->>m: Pago confirmado
    deactivate b
    m->>mobile: Envia push
    mobile->>u: Lee la push

En este ejemplo, hemos elegido declarar los participantes y al actor en la parte superior, usando un alias. Internamente nos referiremos a ellos como b, m, mobile o u, pero en el gráfico aparecerán los nombres completos (Banco, Microservicio, App móvil y Usuario).

Podemos apreciar que hemos introducido activate m y deactivate m haciendo sandwich a otra instrucción. Con esto, Mermaid creará una barrita que indica que algo se está procesando en ese intervalo pero nosotros además hemos añadido un flujo a sí mismo para especificar que se está ejecutando.

Aquí os dejamos la documentación por si queréis revisar.

Más tipos de gráficos

Entidad – Relacion

erDiagram
    USUARIO {
        string id PK
        string email
        string fecha_nacimiento
        string nombre
        string apellido
    }

    USUARIO ||..|{ PEDIDO: tiene

    PEDIDO {
        string id_usuario FK, PK
        string referencia PK
        string fecha_pedido
        float precio
        string direccion
    }

    USUARIO ||..|{ DATOS_BANCARIOS: tiene
    
    DATOS_BANCARIOS {
        string id PK
        string id_usuario FK
        string numero_cuenta
    }

Aquí podemos ver cómo creamos un diagrama de Entidad-Relacion y además podemos especificar los distintos tipos de relación (O-N, 1-1, 0-N, 1-N) como las claves que son primarias (PK) o foráneas (FK). Aquí su documentación: http://mermaid.js.org/syntax/entityRelationshipDiagram.html

Diagrama de estados

Un sencillo ejemplo para renovar el DNI:

flowchart TD
    A[Renovar dni] --> B{Esta caducado}
    B -->|Si| D[Cita previa]
    B -->|No| E[Renovar desde web]
    E --> F
    D --> F[DNI renovado]

Aquí lo más interesante es cómo crear un nodo de decisión para ramificar los gráficos, en este caso se hace englobando entre llaves ({}) el texto que describe a un nodo.

La documentación de los gráficos de flujo: http://mermaid.js.org/syntax/stateDiagram.html

Conclusiones

Como habrás podido observar, es muy sencillo hace unos gráficos completos para poder documentar en condiciones nuestros flujos en los README de nuestros proyectos. Desde aquí te animamos a usarlos, seguro que a la larga es una decisión que acabas agradeciendo.