Arquitecto Mermaid - Habilidad de Diagramas y Documentación Jerárquica

Sistema de diagramas y documentación Mermaid con guías especializadas y capacidades de conversión de código a diagrama.

Tabla de Contenidos

Árbol de Decisión
Wiki de GitHub, WikiTicket y Confluence
Guías y Recursos Disponibles
Patrones de Uso
Flujo de Trabajo Robusto
Símbolos Semánticos Unicode
Utilidades Python
Ejemplos del Árbol de Decisión
Estilo de Alto Contraste
Organización de Archivos
Resumen del Flujo de Trabajo
Cuándo Usar Qué
Mejores Prácticas
Ruta de Aprendizaje

Árbol de Decisión

Cómo funciona esta habilidad:

El usuario hace una solicitud → La habilidad analiza la intención
La habilidad determina el tipo de diagrama/documento → Carga la(s) guía(s) apropiada(s)
La IA lee la guía especializada → Genera el diagrama/documento usando plantillas
Resultado entregado → Con opciones de validación y exportación

Análisis de la Intención del Usuario:

flowchart TD
    Inicio([Solicitud del Usuario]) --> Analizar{Analizar Intención}

    Analizar -->|"flujo de trabajo, proceso, lógica de negocio"| Actividad[Cargar Guía de Diagramas de Actividad<br/>references/guides/diagrams/activity-diagrams.md]
    Analizar -->|"infraestructura, despliegue, nube"| Despliegue[Cargar Guía de Diagramas de Despliegue<br/>references/guides/diagrams/deployment-diagrams.md]
    Analizar -->|"arquitectura del sistema, componentes"| Arquitectura[Cargar Guía de Arquitectura<br/>references/guides/diagrams/architecture-diagrams.md]
    Analizar -->|"flujo de API, interacciones"| Secuencia[Cargar Guía de Diagramas de Secuencia<br/>references/guides/diagrams/sequence-diagrams.md]
    Analizar -->|"clase, ER, estado, wiki, walkthrough"| GuiaWiki[Cargar Guía de WikiTicket y GitHub<br/>references/guides/wiki-ticket-and-github.md]
    Analizar -->|"código a diagrama"| CodigoADiagrama[Cargar Guía de Código a Diagrama<br/>references/guides/code-to-diagram/ + examples/]
    Analizar -->|"documento de diseño, documentación completa"| DocDiseno[Cargar Plantilla de Documento de Diseño<br/>assets/*-design-template.md]
    Analizar -->|"símbolos unicode, iconos"| Unicode[Cargar Guía de Símbolos Unicode<br/>references/guides/unicode-symbols/guide.md]
    Analizar -->|"extraer, validar, convertir"| Scripts[Usar Scripts Python<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Actividad --> Generar[Generar Diagrama]
    Despliegue --> Generar
    Arquitectura --> Generar
    Secuencia --> Generar
    GuiaWiki --> Generar
    CodigoADiagrama --> Generar
    DocDiseno --> Generar
    Unicode --> Generar
    Scripts --> Ejecutar[Ejecutar Script]

    Generar --> Validar{¿Validar?}
    Validar -->|Sí| EjecutarValidacion[Ejecutar validación mmdc]
    Validar -->|No| Salida
    EjecutarValidacion --> Salida[Entregar Resultado]
    Ejecutar --> Salida

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guia fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef accion fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analizar,Validar decision
    class Actividad,Despliegue,Arquitectura,Secuencia,GuiaWiki,CodigoADiagrama,DocDiseno,Unicode,Scripts guia
    class Generar,Ejecutar,EjecutarValidacion,Salida accion

Guías y Recursos Disponibles

Guías por Tipo de Diagrama (`references/guides/diagrams/`)

Guía	Ruta Completa	Cargar Cuando el Usuario Quiere	Ejemplos
Diagramas de Actividad	`references/guides/diagrams/activity-diagrams.md`	Flujos de trabajo, procesos, lógica de negocio, flujos de usuario, árboles de decisión	"Mostrar flujo de pago", "Documentar pipeline ETL", "Crear flujo de aprobación"
Diagramas de Despliegue	`references/guides/diagrams/deployment-diagrams.md`	Infraestructura, arquitectura en la nube, K8s, serverless, topología de red	"Mostrar arquitectura AWS", "Documentar despliegue en GCP", "Crear diagrama K8s"
Diagramas de Arquitectura	`references/guides/diagrams/architecture-diagrams.md`	Arquitectura del sistema, diseño de componentes, estructura de alto nivel	"Mostrar componentes del sistema", "Documentar microservicios", "Vista general de arquitectura"
Diagramas de Secuencia	`references/guides/diagrams/sequence-diagrams.md`	Interacciones de API, comunicación entre servicios, flujos de solicitud/respuesta	"Mostrar secuencia de llamadas a API", "Documentar flujo de autenticación", "Interacciones entre servicios"
WikiTicket / GitHub / Confluence	`references/guides/wiki-ticket-and-github.md`	Documentos de diseño, walkthroughs, requisitos, publicación en wiki, imágenes para Confluence	"documento de arquitectura", "código walkthrough", "wiki", "Confluence"

Por defecto para WikiTicket y wiki de GitHub es esta habilidad, incluyendo classDiagram, erDiagram y stateDiagram-v2. No envíes esos a PlantUML. Si GitHub falla al renderizar C4 / architecture-beta / block-beta, recurre a flowchart TD.

Guía de Código a Diagrama y Ejemplos

Recurso	Ruta Completa	Qué Proporciona
Guía Maestra	`references/guides/code-to-diagram/README.md`	Flujo de trabajo completo para analizar cualquier base de código y extraer diagramas
Spring Boot	`examples/spring-boot/README.md`	Arquitectura Controlador→Servicio→Repositorio, configuración de despliegue, secuencia a partir de métodos, actividad a partir de lógica de negocio
FastAPI	`examples/fastapi/README.md`	Patrones asíncronos en Python, modelos Pydantic, inyección de dependencias, despliegue en la nube
React	`examples/react/README.md`	Jerarquía de componentes, gestión de estado, flujo de datos, pipeline de compilación
Python ETL	`examples/python-etl/README.md`	Pipeline de datos, pasos de transformación, manejo de errores, programación
Node/Express	`examples/node-webapp/README.md`	Cadena de middleware, manejadores de rutas, patrones asíncronos, despliegue
Aplicación Web Java	`examples/java-webapp/README.md`	MVC tradicional, contenedores de servlets, despliegue WAR

Plantillas de Documentos de Diseño

Plantilla	Ruta Completa	Usar Para	Cargar Cuando
Diseño de Arquitectura	`assets/architecture-design-template.md`	Arquitectura de todo el sistema	"Crear documento de arquitectura", "Documentar diseño del sistema"
Diseño de API	`assets/api-design-template.md`	Especificaciones de API	"Documento de diseño de API", "Documentar API REST"
Diseño de Funcionalidad	`assets/feature-design-template.md`	Planificación de funcionalidades	"Diseño de funcionalidad", "Planificar nueva funcionalidad"
Diseño de Base de Datos	`assets/database-design-template.md`	Esquema de base de datos	"Diseño de base de datos", "Documentar esquema"
Diseño de Sistema	`assets/system-design-template.md`	Sistema completo	"Documento de diseño del sistema", "Documentación completa del sistema"

Guía de Símbolos Unicode

Ruta Completa: references/guides/unicode-symbols/guide.md

Cargar cuando el usuario mencione: "símbolos unicode", "emoji en diagramas", "iconos semánticos", "añadir símbolos"

Referencia Rápida:

📦 Infraestructura: ☁️ 🌐 🔌 📡 🗄️
⚙️ Cómputo: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
💾 Datos: 💾 📦 📊 📈 🗃️ 🧊
📨 Mensajería: 📨 📬 📤 📥 🐰 📢
🔐 Seguridad: 🔐 🔑 🛡️ 🚪 👤 🎫
📝 Monitoreo: 📝 📊 🚨 ⚠️ ✅ ❌

Scripts Python (`scripts/`)

Script	Usar Para	Cargar Cuando
`extract_mermaid.py`	Extraer diagramas de Markdown, validar sintaxis, reemplazar con imágenes	"extraer diagramas", "validar mermaid", "encontrar todos los diagramas"
`mermaid_to_image.py`	Convertir .mmd a PNG/SVG, conversión por lotes, temas personalizados	"convertir a imagen", "renderizar diagrama", "crear PNG"
`resilient_diagram.py`	Flujo de trabajo completo: guardar .mmd, generar imagen, validar, recuperación de errores	"generar diagrama", "crear diagrama con validación", "diagrama robusto"

Wiki de GitHub, WikiTicket y Confluence

Carga references/guides/wiki-ticket-and-github.md para documentos de diseño de WikiTicket, walkthroughs de código, requisitos, wiki de GitHub o Confluence.

Destino	Qué Entregar
Wiki de GitHub / GFM	Bloque de código `mermaid` con delimitadores. GitHub renderiza class, ER, state, sequence, flowchart, C4.
Confluence / Notion / Word / PDF	Renderizar también PNG o SVG (`scripts/resilient_diagram.py` o `mmdc`) y subir la imagen. No confíes en que Confluence renderice Mermaid.

PlantUML es opt-in para wireframes de Salt, casos de uso, temporización, ArchiMate, nwdiag y WBS. Esos siempre se entregan como PNG o SVG.

Patrones de Uso

Patrones de solicitud comunes y selección de guías. Consulta Cuándo Usar Qué para un mapeo completo.

Patrón	Ejemplo de Solicitud	Guías a Cargar
Diagrama Único	"Crear diagrama de actividad para el flujo de inicio de sesión"	Guía del tipo de diagrama + Símbolos Unicode
Código a Diagrama	"Generar despliegue desde application.yml"	Ejemplo del framework + Guía de despliegue
Documento de Diseño	"Crear documento de diseño de API"	Plantilla de assets/ + Guías de diagramas relevantes
Extraer/Validar	"Extraer diagramas de design.md"	Usar `scripts/extract_mermaid.py`
Convertir Lote	"Convertir todos los .mmd a PNG"	Usar `scripts/mermaid_to_image.py`

Flujo de Trabajo Robusto

CRÍTICO: Este es el enfoque recomendado para TODA generación de diagramas. Asegura validación, recuperación de errores y organización consistente de archivos.

Guía Completa: references/guides/resilient-workflow.md

Resumen del Flujo de Trabajo

flowchart LR
    A[1. Identificar Tipo] --> B[2. Guardar .mmd + Imagen]
    B --> C{3. ¿Válido?}
    C -->|Sí| D[4. Añadir a Markdown]
    C -->|No| E[5. Recuperación de Errores]
    E --> F{¿Solución Encontrada?}
    F -->|Sí| A
    F -->|No| G[Buscar en Externos]
    G --> A

    classDef paso fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G paso
    class C,F decision

Principio Clave

NUNCA añadas un diagrama a markdown hasta que pase la validación. Esto evita diagramas rotos en la documentación.

Usando el Script (Recomendado)

# Generar con recuperación completa de errores
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

Salida: Archivos .mmd y .png en el directorio ./diagrams/.

Convención de Nombres de Archivos

./diagrams/<archivo_markdown>_<num>_<tipo>_<título>.mmd
./diagrams/<archivo_markdown>_<num>_<tipo>_<título>.png

Ejemplo: ./diagrams/api_design_01_sequence_auth_flow.png

Prioridad de Recuperación de Errores

Cuando la validación falla, el flujo de trabajo automáticamente:

Revisar la guía de solución de problemas - references/guides/troubleshooting.md (28 errores documentados)
Buscar con perplexity - MCP perplexity_ask para preguntas de sintaxis
Buscar con brave - MCP brave_web_search para soluciones recientes
Preguntar a gemini - Habilidad gemini para una perspectiva alternativa
Búsqueda general - Herramienta WebSearch como alternativa

Pasos Manuales Alternativos

Si el script no está disponible:

Identificar el tipo de diagrama desde la primera línea (flowchart, sequence, etc.)
Cargar la guía de referencia desde references/guides/diagrams/
Guardar en ./diagrams/<archivo_markdown>_<num>_<tipo>_<título>.mmd
Validar: mmdc -i file.mmd -o file.png -b transparent
En caso de error: Buscar en references/guides/troubleshooting.md el error correspondiente
Si no se encuentra: Usar herramientas de búsqueda en el orden de prioridad anterior
Añadir referencia: ![Descripción](./diagrams/nombre_archivo.png)

Patrón 6: Generación Robusta de Diagramas

Usuario: "Crea un diagrama de secuencia y añádelo al documento de diseño"

Acciones de la Habilidad:

Identificar intención: generación de diagrama + integración en markdown
Cargar guía de flujo de trabajo: references/guides/resilient-workflow.md
Identificar tipo de diagrama: secuencia
Cargar guía de diagrama: references/guides/diagrams/sequence-diagrams.md
Generar código Mermaid usando plantillas

Ejecutar flujo de trabajo robusto:

python scripts/resilient_diagram.py \
    --code "[código generado]" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "api_sequence" \
    --json

Si la validación falla → Aplicar corrección de solución de problemas → Reintentar
En caso de éxito → Añadir ![Secuencia API](./diagrams/design_doc_01_sequence_api_sequence.png) al markdown

Símbolos Semánticos Unicode

Usa siempre símbolos Unicode para mejorar la claridad del diagrama. Patrones comunes:

Infraestructura y Despliegue

graph TB
    Cliente[👤 Usuario] --> LB[🌐 Balanceador de Carga]
    LB --> App1[⚙️ Servidor de Aplicación 1]
    LB --> App2[⚙️ Servidor de Aplicación 2]
    App1 --> BD[(💾 Base de Datos)]
    App1 --> Cache[(⚡ Redis)]

Flujo de Actividad con Estados

flowchart TD
    Inicio([🚀 Inicio]) --> Procesar[⚙️ Procesar Datos]
    Procesar --> Verificar{✓ ¿Válido?}
    Verificar -->|Sí| Guardar[💾 Guardar]
    Verificar -->|No| Error[❌ Error]
    Guardar --> Completo([✅ Completo])

Arquitectura de Microservicios

graph TB
    API[🌐 Puerta de Enlace API] --> Auth[🔐 Servicio de Autenticación]
    API --> Pedidos[📋 Servicio de Pedidos]
    Pedidos --> Cola[📬 Cola de Mensajes]
    Cola --> Worker[⚙️ Trabajador en Segundo Plano]
    Worker --> Almacenamiento[📦 Almacenamiento de Objetos]

Para la referencia completa de símbolos, carga: references/guides/unicode-symbols/guide.md

Utilidades Python

Extraer Diagramas Mermaid

# Listar todos los diagramas
python scripts/extract_mermaid.py documento.md --list-only

# Extraer a archivos separados
python scripts/extract_mermaid.py documento.md --output-dir diagrams/

# Validar todos los diagramas
python scripts/extract_mermaid.py documento.md --validate

# Reemplazar con referencias de imagen (para subir a Confluence)
python scripts/extract_mermaid.py documento.md --replace-with-images \
  --image-format png --output-markdown salida.md

Convertir a Imágenes

# Conversión única
python scripts/mermaid_to_image.py diagrama.mmd salida.png

# Con configuraciones personalizadas
python scripts/mermaid_to_image.py diagrama.mmd salida.svg \
  --theme dark --background white --width 1200

# Convertir directorio por lotes
python scripts/mermaid_to_image.py diagrams/ salida/ --format png --recursive

# Desde stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_

...[truncado para traducción]

Arquitecto Mermaid - Habilidad de Diagramas y Documentación Jer…

¿Qué es Arquitecto Mermaid - Habilidad de Diagramas y Documentación Jer…?

Preguntar en tu IA favorita

Vista previa

Documentación