lidorshimoni/visualize

Visualize: Patrón de Visualización de Arquitectura y Flujos

Intención

Transformar arquitecturas textuales, algoritmos complejos, interacciones multi-agente y modelos de datos en diagramas visuales inequívocos utilizando la sintaxis estándar de Mermaid.

Fundamento Teórico

Basado en la teoría de carga cognitiva y el Modelo C4 para Arquitectura de Software (Brown, 2018). Los modelos visuales fundamentan las descripciones abstractas de sistemas, haciendo que los límites, flujos de datos y transiciones de estado sean instantáneamente verificables tanto por humanos como por agentes.

Arquetipos de Diagrama Estándar

1. Arquitectura de Componentes y Límites (C4 Contenedor / Componente)

Usa flowchart TD o flowchart LR con subgrafos para representar capas arquitectónicas:

flowchart TD
    subgraph Client["Capa Cliente"]
        Web["Aplicación Web (React)"]
        CLI["Herramienta CLI (Python)"]
    end

    subgraph Gateway["Puerta de Enlace API"]
        Proxy["Proxy Inverso / Nginx"]
        Auth["Servicio de Autenticación (JWT)"]
    end

    subgraph Core["Servicios Centrales"]
        App["Motor de Aplicación"]
        Worker["Trabajador Asíncrono en Segundo Plano"]
    end

    subgraph Data["Capa de Persistencia"]
        DB[("PostgreSQL")]
        Queue[("Cola Redis")]
    end

    Web --> Proxy
    CLI --> Proxy
    Proxy --> Auth
    Auth --> App
    App --> Queue
    Queue --> Worker
    Worker --> DB
    App --> DB

2. Flujo de Solicitud / Respuesta y Protocolo (Diagrama de Secuencia)

Usa sequenceDiagram con líneas de vida de activación para mostrar interacciones cronológicas:

sequenceDiagram
    autonumber
    actor Usuario
    participant Agente as Agente de Codificación
    participant Herramienta as Ejecutor de Herramientas
    participant Git as Control de Versiones

    Usuario->>Agente: Solicitar implementación de funcionalidad
    Agente->>Herramienta: Ejecutar prueba fallida (Rojo)
    Herramienta-->>Agente: Prueba falló como se esperaba
    Agente->>Herramienta: Escribir código mínimo (Verde)
    Agente->>Herramienta: Ejecutar suite de pruebas
    Herramienta-->>Agente: Todas las pruebas pasaron
    Agente->>Git: Confirmar cambio atómico
    Git-->>Agente: Hash de confirmación generado
    Agente-->>Usuario: Reportar tarea completada

3. Máquinas de Estado y Ciclos de Vida (Diagrama de Estado)

Usa stateDiagram-v2 para estados de entidad, estados de tarea o ciclos de vida de conexiones:

stateDiagram-v2
    [*] --> Borrador
    Borrador --> EnRevisión: Enviar para Revisión
    EnRevisión --> Aprobado: Pasar Verificación
    EnRevisión --> RequiereCambios: Bloqueador Encontrado
    RequiereCambios --> EnRevisión: Reenviar Corrección
    Aprobado --> EnProgreso: Iniciar Implementación
    EnProgreso --> Completado: Todas las Pruebas Pasan
    Completado --> [*]

4. Modelos de Datos y Relaciones (Diagrama Entidad-Relación)

Usa erDiagram para esquemas relacionales y modelos de dominio:

erDiagram
    PROYECTO ||--o{ ESPECIFICACION : contiene
    ESPECIFICACION ||--o{ TICKET : se_descompone_en
    TICKET ||--o{ COMMIT : implementado_por
    TICKET {
        string id PK
        string titulo
        string estado
        string bloqueado_por
    }

Reglas de Seguridad de Sintaxis Mermaid

1. Siempre encierra entre comillas las etiquetas de nodo con caracteres especiales:
   • id["Etiqueta (Información Extra)"] en lugar de id[Etiqueta (Información Extra)].
2. Solo tipos de diagrama soportados:
   • Diagramas de flujo (flowchart TD), Secuencia (sequenceDiagram), Estado (stateDiagram-v2), Clase (classDiagram), ER (erDiagram).
3. Evita HTML sin procesar en el texto del nodo: Usa Markdown puro o texto limpio dentro de las cadenas de nodo.

---

Citas y Procedencia

1. El Modelo C4 para Arquitectura de Software: Brown, S. (2018). Software Architecture for Developers: Visualise, document and explore your software architecture. Leanpub.
2. Estándar de Gráficos Mermaid: Sveidqvist, K., et al. (2014-2026). Mermaid: Markdown-inspired syntax for generating charts and diagrams (https://mermaid.js.org/).
3. Teoría de Carga Cognitiva en Visualización de Software: Sweller, J. (2011). Cognitive Load Theory. Psychology of Learning and Motivation, Vol. 55.