Archify: qué es, cómo crear diagramas con IA y cuándo necesitas otra herramienta

Crear un diagrama de arquitectura a partir de una descripción técnica puede llevar bastante tiempo. Hay que identificar los componentes, dibujar las conexiones y actualizar el resultado cada vez que cambia el sistema. Archify propone otra forma de trabajar: describir lo que necesitas a un agente de programación y dejar que genere un diagrama HTML interactivo.

Archify es un proyecto de código abierto pensado para trabajar con agentes como Claude Code, Codex, Cursor y OpenCode. Permite convertir información técnica en representaciones visuales que se pueden abrir en un navegador, explorar y compartir. Su popularidad también ha llamado la atención: el proyecto superó las 73.000 estrellas en GitHub y destacó en las tendencias de la plataforma a finales de agosto de 2026.

Sin embargo, hay una diferencia importante entre generar un diagrama y ejecutar el proceso que representa. Archify puede ayudarte a documentar una arquitectura o explicar un flujo de trabajo, pero no debe confundirse con un motor de automatización.

En esta guía veremos cómo funciona Archify, cómo organizar varias vistas de un mismo sistema, cómo representar flujos similares a los de AWS Step Functions y qué alternativas conviene considerar según necesites dibujar, modelar o ejecutar procesos.

Qué es Archify y para qué sirve

Archify es una herramienta de código abierto con licencia MIT que transforma descripciones textuales e información técnica en diagramas interactivos. No es un editor web independiente al que accedes para dibujar manualmente. Su funcionamiento se basa en una habilidad que se instala en un agente de programación compatible.

Entre los agentes documentados por el proyecto se encuentran Claude Code, Codex, Cursor, OpenCode y Copilot. La instalación puede realizarse mediante un comando de este tipo:

npx skills add archify

El comando exacto y los requisitos pueden cambiar entre versiones, por lo que conviene consultar las instrucciones actuales del repositorio antes de instalarlo.

Una vez configurado, puedes pedirle al agente que represente una arquitectura, describa las relaciones entre servicios o convierta una explicación técnica en un flujo visual. El agente prepara los datos estructurados y el renderizador genera un archivo HTML que se puede abrir en el navegador.

Esto resulta útil para documentar repositorios, explicar sistemas a otros miembros del equipo y explorar procesos sin construir cada elemento a mano.

Funciones y limitaciones de Archify

Función	Qué permite hacer	Qué debes tener en cuenta
Generación de diagramas con IA	Crear diagramas a partir de descripciones	El resultado depende del agente y de las instrucciones
Tipos de diagrama	Representar arquitecturas, secuencias, flujos de datos y ciclos de vida	Cada tipo utiliza su propia estructura de datos
Navegación interactiva	Explorar nodos, conexiones y recorridos	La interacción depende del artefacto generado
Referencias al código	Asociar elementos y afirmaciones con fuentes del repositorio	Las referencias deben ser verificables
Comparación de arquitecturas	Mostrar elementos añadidos, eliminados o modificados	Se utiliza el comando archify compare
Exportación	Obtener formatos como PNG, JPEG, WebP, SVG y WebM	Los formatos disponibles dependen de la versión
Edición visual libre	Dibujar y retocar elementos como en un editor tradicional	No es su principal objetivo
Ejecución de procesos	Lanzar tareas, gestionar reintentos y mantener el estado	No está documentado como motor de ejecución

La última diferencia es especialmente importante. Archify puede mostrar qué pasos debería seguir un proceso, pero no se encarga de ejecutarlos, conservar su estado ni recuperar automáticamente una operación fallida.

Cómo funcionan los diagramas generados con inteligencia artificial

Las herramientas de diagramación a partir de texto, conocidas como text-to-diagram, llevan años existiendo. Mermaid y PlantUML, por ejemplo, permiten definir diagramas mediante texto y generar una representación visual.

Archify cambia la forma de preparar esa definición: en lugar de escribir toda la sintaxis manualmente, describes el resultado que necesitas y dejas que un agente de IA construya el modelo.

La diferencia no consiste únicamente en ahorrar tiempo. También importa cómo se comprueba que el diagrama representa correctamente el sistema real.

Por qué es importante verificar las referencias al código

Imagina que un diagrama afirma que el servicio de pedidos llama directamente al servicio de pagos. La relación parece lógica, pero podría no corresponder a la arquitectura actual: quizá la comunicación se realiza mediante una cola de mensajes o a través de otro servicio.

Un modelo de IA puede generar conexiones plausibles que no existen en el repositorio. Por eso es importante vincular las afirmaciones técnicas con archivos, funciones u otras referencias verificables.

Archify incorpora un mecanismo de validación de evidencias para las referencias que utiliza. Si una referencia no existe o no coincide con lo esperado, la construcción puede fallar en lugar de producir un artefacto aparentemente correcto. Este comportamiento depende de las comprobaciones configuradas y de la versión utilizada; no garantiza por sí solo que todas las relaciones del diagrama sean correctas.

Para documentar una arquitectura real, sigue siendo necesario revisar las conexiones, las dependencias y los límites entre componentes.

Entrada Mermaid y generación del HTML

Archify documenta la compatibilidad con definiciones Mermaid como formato de entrada. Esto puede facilitar la transición si ya mantienes diagramas en esa sintaxis.

En cuanto al renderizado, conviene distinguir entre el formato de entrada y la tecnología que produce el resultado final. Algunas descripciones técnicas del proyecto señalan que los diagramas se incorporan como SVG en línea dentro del HTML, en lugar de depender de Mermaid.js durante la visualización. Como existen explicaciones contradictorias, comprueba el comportamiento de la versión que instales si este detalle afecta a tu integración.

Lo importante para el uso cotidiano es que el resultado se entrega como un artefacto HTML autocontenido que puedes abrir en un navegador, sin necesidad de utilizar un editor gráfico específico para visualizarlo.

Multiview: cómo representar un sistema desde varias perspectivas

En arquitectura de software, multiview suele referirse a la representación de un mismo sistema desde diferentes perspectivas. No todas las personas necesitan ver los mismos detalles: un responsable de negocio busca entender el proceso, un desarrollador necesita conocer las dependencias y el equipo de operaciones quiere saber cómo se gestionan los fallos.

No hay que asumir que Archify ofrece una función nativa llamada Multiview que mantenga varios diagramas sincronizados automáticamente. Es posible organizar distintas vistas mediante artefactos separados, pero la sincronización y la gestión de cambios deben comprobarse o resolverse mediante una metodología propia.

Ejemplo: un sistema de pedidos en tres vistas

Vista 1. Proceso de negocio

Explica qué ocurre con un pedido desde que se recibe hasta que se entrega. Incluye la validación, el pago, la preparación y las decisiones principales, como comprobar si hay existencias o si se autoriza el cobro.

Vista 2. Arquitectura técnica

Muestra los componentes que intervienen: API de pedidos, servicio de pagos, inventario y logística. Aquí importan las llamadas entre servicios, los eventos y los datos intercambiados.

Vista 3. Errores y recuperación

Describe qué sucede si falla una conexión, se rechaza un pago, no hay inventario o el transportista no confirma el envío. Cada situación necesita una respuesta definida, como reintentar, cancelar, compensar una operación o solicitar intervención manual.

Las tres vistas pueden generarse con Archify por separado. Para que sigan describiendo el mismo sistema, conviene establecer algunas reglas desde el principio:

1. Utiliza identificadores estables. Nombres como ORDER-VALIDATION, PAYMENT-AUTH y STOCK-CHECK permiten relacionar componentes y pasos entre diagramas.
2. Mantén una fuente de verdad. Los nombres de los servicios, sus interfaces y sus dependencias deben proceder del código o de la documentación vigente.
3. Vincula los elementos con su origen. Siempre que sea posible, relaciona cada componente con archivos, funciones o definiciones concretas.
4. Revisa las vistas cuando cambie la arquitectura. Si se sustituye la pasarela de pago, comprueba también el proceso de negocio y las rutas de error.

Si el proyecto necesita sincronización automática, control de versiones de modelos o políticas formales de arquitectura, comprueba que la herramienta elegida incluya esas funciones. Un repositorio compartido y unas convenciones claras ayudan, pero no sustituyen un sistema de gobierno de modelos cuando este es necesario.

Archify y AWS Step Functions: diagramar no es ejecutar

AWS Step Functions permite construir flujos de trabajo mediante máquinas de estados. Cada estado representa una operación, una decisión, una espera o un resultado final. El servicio ejecuta el flujo y gestiona las transiciones según las reglas definidas.

Las máquinas de estados se describen mediante Amazon States Language (ASL), un lenguaje declarativo basado en JSON. Step Functions puede ejecutar tareas, evaluar condiciones, lanzar ramas paralelas y gestionar determinados errores mediante políticas configuradas.

Archify puede utilizarse para explicar visualmente una lógica similar. Sin embargo, no debe darse por hecho que ejecuta máquinas de estados de Step Functions, importa o exporta ASL o se integra directamente con AWS. Esas capacidades deben verificarse en la documentación de la versión correspondiente.

Estados principales de AWS Step Functions

Estado	Función	Ejemplo en una tienda
Task	Ejecutar una tarea	Autorizar un pago
Choice	Elegir una ruta según una condición	Comprobar si hay existencias
Parallel	Ejecutar varias ramas en paralelo	Actualizar analítica y preparar documentación
Map	Repetir una operación para varios elementos	Procesar los artículos de un pedido
Wait	Esperar antes de continuar	Esperar una confirmación logística
Pass	Pasar o transformar datos sin ejecutar una tarea externa	Preparar el contexto del pedido
Succeed	Terminar correctamente	Pedido completado
Fail	Terminar con un error	Pedido no recuperable

Dibujar estos estados en un diagrama no reproduce su comportamiento real. Una bifurcación visual no implementa las condiciones de Choice, y dos flechas paralelas no garantizan la sincronización que necesita Parallel.

También hay que definir qué ocurre cuando ninguna condición coincide. En un estado Choice, si no existe una transición válida ni una ruta predeterminada, la ejecución puede fallar. Ese tipo de detalle debe quedar reflejado en el modelo y en la implementación.

Reintentos, errores e idempotencia

Un flujo de trabajo fiable distingue entre un fallo temporal y un resultado de negocio. No todas las operaciones deben repetirse cuando algo sale mal.

Situación	Tratamiento recomendado
Interrupción temporal de una API	Reintentar con intervalos crecientes y un máximo de intentos
Pago rechazado por el banco	Solicitar otro método de pago o cancelar
Servicio que no responde	Aplicar un tiempo de espera y definir una ruta de recuperación
Inventario insuficiente	Ofrecer una alternativa, permitir una reserva parcial o cancelar
Reintentos agotados	Registrar el fallo y escalarlo si procede
Error al enviar la confirmación	Reintentar la notificación sin crear otro pedido

Step Functions permite configurar políticas Retry y Catch en los estados compatibles, además de tiempos de espera. La política concreta depende del tipo de estado, del error y de la configuración de la máquina.

Otro concepto fundamental es la idempotencia: repetir una petición no debería generar dos cargos ni crear dos pedidos. Antes de volver a autorizar un pago o reservar inventario, el sistema debe comprobar si la operación anterior llegó a completarse.

El caso más delicado es aquel en el que no se conoce el resultado. Por ejemplo, una solicitud de pago puede haber sido procesada aunque la respuesta se pierda por un problema de red. Repetirla sin consultar su estado podría provocar un cargo duplicado.

La observabilidad también importa. En producción, el equipo necesita conocer el estado real de las ejecuciones y consultar los registros disponibles. Step Functions ofrece información sobre las ejecuciones y puede integrarse con CloudWatch, según el tipo de flujo y la configuración. Un diagrama de Archify puede indicar dónde se espera registrar un evento, pero no sustituye a los registros ni a la monitorización.

Para diseñar e implementar el flujo directamente en AWS, la opción oficial es Workflow Studio, el diseñador visual de Step Functions. Archify puede complementar ese trabajo como herramienta de documentación y comunicación técnica.

Otras plataformas que merece la pena evaluar para la orquestación de procesos son Temporal, Apache Airflow, n8n y Kestra. No resuelven exactamente el mismo problema: la elección depende de los requisitos de ejecución, el entorno de despliegue y las capacidades del equipo.

Ejemplo práctico: diseñar el flujo de pedidos y gestionar sus errores

Consideremos una tienda en línea que recibe un pedido, comprueba los datos del cliente, reserva inventario, autoriza el pago y prepara el envío.

Antes de implementar el proceso, conviene definir los pasos y sus condiciones de salida.

Estado	Acción	Siguiente paso	Tratamiento de errores
Recibir pedido	Registrar el pedido y asignar un identificador	Validar cliente	Rechazar datos mal formados y evitar duplicados
Validar cliente	Comprobar identidad, dirección y reglas	Comprobar inventario	Solicitar correcciones o finalizar como inválido
Comprobar inventario	Consultar disponibilidad y reservar unidades	Autorizar pago o resolver falta de stock	Reintentar solo los fallos temporales de consulta
Autorizar pago	Solicitar autorización a la pasarela	Preparar pedido si se autoriza	Tratar el rechazo como resultado de negocio
Preparar pedido	Preparar el paquete y crear la expedición	Notificar al cliente	Liberar reservas o aplicar compensaciones si el proceso no puede continuar
Notificar	Enviar la confirmación	Finalizar	Reintentar sin duplicar el pedido
Recuperar error	Aplicar reintentos o compensaciones	Reanudar, escalar o finalizar	Limitar los intentos y registrar la causa
Finalizar	Registrar el estado definitivo	Fin	Distinguir éxito, cancelación y fallo

Una representación simplificada de la lógica podría ser la siguiente:

recibir_pedido()
validar_cliente_y_datos()

si los_datos_no_son_validos:
    finalizar_como_pedido_invalido

resultado_stock = comprobar_inventario()

si resultado_stock == SIN_EXISTENCIAS:
    ofrecer_alternativa_o_cancelar

si resultado_stock == ERROR_TEMPORAL:
    reintentar_hasta_el_limite
    si sigue_fallando:
        enviar_a_revision

resultado_pago = autorizar_pago()

si resultado_pago == RECHAZADO:
    liberar_reservas
    solicitar_otro_metodo_de_pago_o_cancelar

si resultado_pago == RESULTADO_DESCONOCIDO:
    consultar_estado_del_pago_antes_de_repetir

preparar_y_enviar_pedido()
notificar_al_cliente()
finalizar_correctamente

Este pseudocódigo sirve para explicar la lógica, pero no es código ejecutable ni una definición ASL válida.

Una implementación real también necesita persistencia del estado, controles de idempotencia, límites de tiempo, autenticación, permisos y compensaciones para los fallos parciales.

Con Archify puedes preparar una vista de negocio y otra técnica del mismo proceso, relacionándolas mediante identificadores compartidos. Para ejecutar el flujo, tendrás que implementar esa lógica en Step Functions u otra plataforma compatible.

Archify frente a otras herramientas de diagramas y procesos

No todas las herramientas de diagramación sirven para lo mismo. Algunas se centran en el dibujo y la colaboración; otras convierten definiciones textuales en gráficos; y otras permiten diseñar procesos que después ejecuta un motor.

Herramienta	Enfoque principal	¿Ejecuta flujos?	Principal limitación
Archify	Diagramas interactivos generados mediante agentes de IA	No está documentado como motor de ejecución	Depende del agente y de la validación del resultado
diagrams.net	Editor gráfico de diagramas	No	La lógica ejecutable debe implementarse aparte
Lucidchart	Diagramación colaborativa y plantillas	No como motor general	Algunas funciones dependen del plan
Miro	Pizarra visual colaborativa	No	No sustituye a una plataforma de orquestación
Mermaid	Diagramas definidos mediante texto	No	Depende de la sintaxis y de los tipos compatibles
PlantUML	Diagramas como código, especialmente UML	No	No valida ni ejecuta la lógica representada
Camunda Modeler	Modelado formal con BPMN	Mediante la plataforma de ejecución de Camunda	Requiere conocer BPMN y configurar el despliegue
AWS Workflow Studio	Diseño visual de máquinas de estados	Sí, mediante Step Functions	Está orientado al entorno de AWS

Mermaid vs. PlantUML: cuál elegir

Mermaid y PlantUML permiten mantener diagramas como texto, algo útil para incluirlos en repositorios y documentación técnica. La diferencia está en sus casos de uso y en las notaciones que ofrecen.

Mermaid encaja bien en proyectos donde los diagramas forman parte de archivos Markdown, wikis o documentación alojada junto al código. Permite representar flujos, secuencias, clases y otros tipos de diagramas mediante una sintaxis relativamente sencilla.

PlantUML resulta especialmente útil cuando se necesitan diagramas UML con más detalle y control sobre la notación. Es una opción que merece la pena considerar en documentación de diseño de software y sistemas con requisitos de representación técnica más formales.

Como regla práctica:

• Elige Mermaid si quieres añadir diagramas a la documentación Markdown con poca fricción.
• Elige PlantUML si necesitas una cobertura UML más amplia o un control más detallado sobre las representaciones.
• Considera Archify si prefieres describir el sistema a un agente y generar una vista interactiva.

Ninguna de estas tres opciones debe confundirse con un motor de ejecución de procesos.

Alternativas gratuitas a Microsoft Visio

Si buscas una alternativa gratuita a Visio para dibujar diagramas manualmente, diagrams.net es una de las primeras herramientas que conviene probar. Funciona en el navegador y permite trabajar con diagramas sin necesidad de contratar una suscripción.

Lucidchart es otra opción para equipos que priorizan la colaboración, las plantillas y el trabajo compartido. Dispone de una modalidad gratuita con limitaciones, por lo que conviene comprobar las condiciones actuales antes de adoptarlo para un proyecto.

Miro puede encajar mejor cuando el trabajo consiste en organizar ideas, preparar mapas de procesos y colaborar en una pizarra visual.

Archify responde a una necesidad diferente: genera diagramas a partir de descripciones y de la información que procesa el agente. Si quieres mover manualmente cada caja, ajustar flechas y retocar el diseño con libertad, un editor gráfico tradicional puede resultar más adecuado.

BPMN y Camunda: cuándo necesitas modelar procesos formalmente

BPMN, siglas de Business Process Model and Notation, es una notación diseñada para representar procesos de negocio mediante elementos definidos, como eventos, actividades, compuertas y flujos de mensajes.

Un diagrama de flujo convencional permite representar un proceso con bastante libertad. BPMN, en cambio, establece reglas y convenciones que ayudan a modelar las interacciones, las decisiones y los distintos participantes de un proceso.

Un modelo BPMN puede convertirse en un proceso ejecutable cuando se implementa y despliega en un motor compatible. Camunda Modeler permite diseñar modelos para la plataforma de Camunda, pero la ejecución depende del entorno y de la configuración correspondiente.

Por eso, la elección entre Archify y Camunda no consiste en decidir cuál dibuja mejor. Archify está orientado a generar documentación visual a partir de descripciones técnicas; Camunda responde a necesidades de modelado formal y automatización de procesos.

Qué herramienta elegir según tus necesidades

La mejor opción depende del resultado que quieras obtener, no solo de cómo se dibujan las conexiones.

Lo que necesitas	Herramienta que conviene evaluar	Por qué
Explicar un repositorio o una arquitectura con un diagrama interactivo	Archify	Generación asistida por agentes y referencias verificables
Dibujar diagramas gratis sin una notación rígida	diagrams.net	Edición visual flexible
Colaborar en diagramas y procesos con un equipo	Lucidchart o Miro	Funciones de colaboración y plantillas
Modelar procesos BPMN para llevarlos a producción	Camunda Modeler y la plataforma Camunda	Notación formal y entorno de ejecución
Mantener diagramas versionados junto al código	Mermaid o PlantUML	Definiciones textuales fáciles de integrar en un repositorio
Ejecutar flujos con reintentos, estados y recuperación de errores	AWS Step Functions, Temporal u otro motor adecuado	Orquestación y control de las ejecuciones
Documentar un sistema desde varias perspectivas	Archify con una convención de vistas, o Lucidchart con capas	Permite separar los niveles de detalle

Una distinción sencilla ayuda a tomar la decisión:

• Documentar: explicar cómo está construido un sistema o cómo debería funcionar.
• Modelar: definir un proceso mediante una notación y unas reglas compartidas.
• Ejecutar: poner en marcha tareas reales, gestionar sus estados y resolver errores.

Archify, Mermaid, PlantUML y diagrams.net pueden formar parte de la documentación. BPMN y Camunda ayudan a modelar procesos, mientras que Step Functions, Temporal y otras plataformas se encargan de la orquestación y la ejecución según sus respectivas capacidades.

No es necesario buscar una única herramienta que resuelva los tres problemas. En muchos proyectos, la solución más práctica consiste en utilizar herramientas diferentes y mantenerlas coordinadas mediante identificadores, documentación y revisiones.

Errores habituales al diseñar diagramas complejos

Incluso un diagrama generado correctamente puede resultar poco útil si mezcla demasiada información o deja fuera los casos importantes.

Error	Por qué causa problemas	Cómo evitarlo
Mezclar la lógica de negocio con la infraestructura	Cuesta distinguir las decisiones comerciales de las operaciones técnicas	Separar las vistas y relacionarlas mediante identificadores
Crear un único diagrama enorme	Las rutas principales y las excepciones se vuelven difíciles de seguir	Dividir el proceso por fases y mantener una vista general
Omitir las rutas de error	El diagrama solo describe el escenario ideal	Añadir fallos, rechazos, cancelaciones y recuperaciones
Reintentar sin un límite	Se pueden repetir operaciones indefinidamente o generar duplicados	Definir errores reintentables, límites y estados finales
Confundir el diagrama con una definición ejecutable	El equipo puede dar por implementadas integraciones que no existen	Identificar claramente los modelos conceptuales y los desplegables
Mantener vistas desactualizadas	La documentación deja de reflejar la arquitectura vigente	Revisar todas las vistas cuando cambien los componentes o sus interfaces
Aceptar sin revisión un diagrama generado con IA	El modelo puede inventar dependencias o conexiones plausibles	Comprobar las referencias y contrastar el resultado con el código

Conclusión: ¿merece la pena utilizar Archify?

Archify merece la pena evaluar si trabajas con agentes de programación y necesitas convertir descripciones técnicas, arquitecturas o repositorios en diagramas interactivos sin dedicar tanto tiempo a dibujarlos manualmente.

Su propuesta resulta especialmente interesante para documentar sistemas, explicar dependencias y preparar varias vistas de una misma arquitectura. La posibilidad de asociar afirmaciones con referencias verificables también es útil cuando el diagrama debe reflejar el código real, aunque sigue siendo necesaria una revisión técnica.

No es, sin embargo, un sustituto universal de las herramientas de diagramación ni de las plataformas de automatización. Para dibujar manualmente, diagrams.net puede ser más apropiado; para mantener diagramas como código, Mermaid o PlantUML; para modelar procesos formalmente, BPMN y Camunda; y para ejecutar flujos con estados, reintentos y recuperación, AWS Step Functions u otro motor de orquestación.

La decisión final depende de una pregunta: ¿necesitas explicar un proceso, definirlo formalmente o ejecutarlo? Una vez aclarado ese objetivo, resulta mucho más sencillo elegir la herramienta adecuada.

Preguntas frecuentes (FAQ)

¿Cómo funcionan los diagramas generados con inteligencia artificial?

Las herramientas de diagramación a partir de texto, conocidas como text-to-diagram , llevan años existiendo. Mermaid y PlantUML, por ejemplo, permiten definir diagramas mediante texto y generar una representación visual.

¿Estados principales de AWS Step Functions?

Dibujar estos estados en un diagrama no reproduce su comportamiento real. Una bifurcación visual no implementa las condiciones de Choice , y dos flechas paralelas no garantizan la sincronización que necesita Parallel .

¿Qué herramienta elegir según tus necesidades?

La mejor opción depende del resultado que quieras obtener, no solo de cómo se dibujan las conexiones.