Archify con agentes: diagramas de arquitectura que se pueden auditar

Si ya le pide diagramas de arquitectura a un agente, probablemente conoce ese momento incómodo: en minutos hay cajas, flechas y un PNG listo para el pull request. Funciona, sí. Hasta que alguien señala una flecha y el código no la justifica. El dibujo feo se descarta. El convincente se adjunta.

En ese camino me encontré con Archify (tt-a1i, 2026a), un proyecto MIT de tt-a1i. Funciona en tres pasos. Generate: el agente escribe el JSON del diagrama. Validate: Archify comprueba que ese archivo cumple las reglas. Deliver: solo si pasa, deja un HTML listo, de un solo archivo, sin servidor.

Quiero mostrar cómo se usa, con un mapa chico y uno de checkout, y también dónde no alcanza.

Para instalarlo:

npx skills add tt-a1i/archify -g

El diagrama se pide en el chat. No hace falta un repositorio ni abrir el CLI. Los comandos doctor, validate y deliver sirven si hay que integrar o diagnosticar (tt-a1i, 2026a, 2026b).

Cuatro nodos

El README empieza por este prompt. Cuatro cajas: navegador, API, Redis y PostgreSQL. Es un ejemplo de caché, no un producto.

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": {
    "title": "Saga de checkout",
    "quality_profile": "showcase",
    "output": "archify-checkout.html",
    "views": [
      {
        "id": "saga-checkout",
        "label": "Saga de checkout",
        "focus": ["clientes", "gateway", "orders", "bus", "inventory", "payment", "delivery"],
        "note": "El pedido entra por el gateway. El orquestador publica al bus. Stock, cobro y envío reaccionan."
      },
      {
        "id": "identidad",
        "label": "Identidad",
        "focus": ["clientes", "gateway", "idp", "orders"],
        "note": "El IdP emite el token. Este mapa dibuja JWT en gateway → idp y orders → idp. No dibuja JWT desde inventory, payment ni delivery."
      },
      {
        "id": "canales-externos",
        "label": "Canales externos",
        "focus": ["canales", "orders", "delivery", "psp"],
        "note": "Los canales pegan webhook al orquestador. No pasan por el gateway."
      }
    ]
  },
  "components": [
    { "id": "canales", "type": "external", "label": "Canales", "sublabel": "apps de delivery", "pos": [880, 80], "size": [148, 64] },
    { "id": "idp", "type": "security", "label": "IdP", "sublabel": "OIDC", "pos": [230, 80], "size": [124, 64] },
    { "id": "authz", "type": "security", "label": "authz", "sublabel": "permisos", "pos": [450, 80], "size": [124, 64] },
    { "id": "clientes", "type": "frontend", "label": "Clientes", "sublabel": "Web / App", "pos": [36, 220], "size": [148, 64] },
    { "id": "gateway", "type": "cloud", "label": "API Gateway", "sublabel": "edge", "pos": [230, 220], "size": [124, 64], "tag": "JWT" },
    { "id": "orders", "type": "backend", "label": "orders", "sublabel": "orquestador", "pos": [450, 220], "size": [148, 64], "tag": "saga" },
    { "id": "postgres", "type": "database", "label": "PostgreSQL", "sublabel": "datos", "pos": [680, 220], "size": [130, 64], "brand": "postgresql" },
    { "id": "bus", "type": "messagebus", "label": "Message bus", "sublabel": "eventos", "pos": [450, 330], "size": [148, 64] },
    { "id": "inventory", "type": "backend", "label": "inventory", "sublabel": "stock", "pos": [230, 440], "size": [140, 64] },
    { "id": "payment", "type": "backend", "label": "payment", "sublabel": "cobro", "pos": [450, 440], "size": [148, 64] },
    { "id": "delivery", "type": "backend", "label": "delivery", "sublabel": "envío", "pos": [680, 330], "size": [130, 64] },
    { "id": "psp", "type": "external", "label": "Pasarela", "sublabel": "cobro externo", "pos": [880, 440], "size": [140, 64] }
  ],
  "boundaries": [
    {
      "kind": "region",
      "label": "Backend",
      "wraps": ["gateway", "idp", "authz", "orders", "postgres", "bus", "inventory", "payment", "delivery"]
    }
  ],
  "connections": [
    { "id": "clientes-gateway", "from": "clientes", "to": "gateway", "label": "HTTPS", "variant": "emphasis" },
    { "id": "gateway-orders", "from": "gateway", "to": "orders", "label": "POST pedido", "variant": "emphasis", "labelDy": 49 },
    { "id": "gateway-idp", "from": "gateway", "to": "idp", "label": "JWT", "variant": "security", "labelDy": -18 },
    { "id": "orders-authz", "from": "orders", "to": "authz", "label": "permisos", "variant": "security", "fromSide": "top", "toSide": "bottom", "labelDy": -36 },
    { "id": "authz-idp", "from": "authz", "to": "idp", "label": "roles", "variant": "security" },
    { "id": "orders-idp", "from": "orders", "to": "idp", "label": "JWT", "variant": "security", "fromSide": "top", "toSide": "right" },
    { "id": "orders-postgres", "from": "orders", "to": "postgres", "label": "SQL" },
    { "id": "orders-bus", "from": "orders", "to": "bus", "label": "pedido.creado", "variant": "dashed", "labelDy": 24 },
    { "id": "bus-inventory", "from": "bus", "to": "inventory", "label": "reservar", "variant": "dashed" },
    { "id": "bus-payment", "from": "bus", "to": "payment", "label": "cobrar", "variant": "dashed", "labelDy": 24 },
    { "id": "bus-delivery", "from": "bus", "to": "delivery", "label": "enviar", "variant": "dashed" },
    { "id": "payment-psp", "from": "payment", "to": "psp", "label": "API cobro", "variant": "emphasis" },
    { "id": "canales-orders", "from": "canales", "to": "orders", "label": "webhook", "variant": "dashed", "fromSide": "bottom", "toSide": "top" }
  ],
  "cards": [
    { "dot": "cyan", "title": "Saga orquestada", "items": ["El pedido entra por el gateway", "El orquestador publica al bus", "Participantes: stock, cobro y envío"] },
    { "dot": "rose", "title": "Identidad", "items": ["El IdP emite el token", "JWT dibujado: gateway → idp y orders → idp", "orders → authz. inventory, payment y delivery no tienen flecha JWT"] },
    { "dot": "emerald", "title": "Fuera del recuadro", "items": ["Otros bounded contexts quedan en cards", "Canales pegan al orquestador, no al gateway", "Cache y tracing no entran al mapa"] }
  ]
}

[](archify-simple.html)

[Abrir el mapa](archify-simple.html) · [JSON](archify-simple.architecture.json)

Doce nodos

El otro extremo es un checkout. Si se pide en una frase, el modelo suele dibujar REST entre el orquestador y el cobro. En este mapa no: el pedido entra por el gateway, el orquestador publica pedido.creado, y stock, cobro y envío escuchan el bus. Los canales mandan el webhook a orders, no al gateway. JWT aparece en el gateway y en orders. Orders consulta permisos.

Mapa de runtime del checkout. Máximo 12 nodos.
Clientes → gateway → orquestador. El orquestador publica al bus.
Participantes: stock, cobro, envío. Webhook de canales al orquestador.
No dibujes REST orquestador → cobro. JWT solo en gateway e orders.
Soporte en cards.

[](archify-checkout.html)

[Abrir el mapa](archify-checkout.html) · [JSON](archify-checkout.architecture.json). El HTML tiene tres lecturas: saga, identidad y canales.

Un mapa se lee cuando tiene pocas cajas (ocho a doce) y cuenta una sola historia (tt-a1i, 2026b). Si más adelante hay dos versiones, Archify puede marcar qué se agregó, se quitó o se movió. Eso no responde si el cambio es seguro de pasar a producción (tt-a1i, 2026a).

Frente a Bizagi y otras herramientas

Al compartir el borrador me preguntaron cómo se compara con Bizagi. Resuelven problemas distintos. Bizagi Modeler es una aplicación de escritorio para modelar procesos de negocio en BPMN 2.0, el estándar de la OMG. El proceso se dibuja arrastrando elementos, y la versión gratuita permite modelar, documentar, simular y publicar (Bizagi, s.f., 2023). El costo está en las horas de una persona frente al lienzo.

Archify no dibuja BPMN. Su costo está en tokens: el agente escribe el JSON y Archify lo valida antes de entregar. Sirve para explicar un sistema técnico en minutos. No reemplaza un modelo de proceso que el negocio va a gobernar o simular. Si el resultado final tiene que ser BPMN, Archify puede ser el primer borrador para conversar, y el modelo formal se construye después en Bizagi.

En el mundo open source también hay diagramas como código. Structurizr genera varias vistas del modelo C4 desde un solo archivo DSL, con licencia Apache 2.0 (Structurizr, s.f.). Mermaid alcanza para un esquema rápido. Lo que distingue a Archify es la validación antes de entregar y el HTML interactivo de un solo archivo. Su propio README aclara que no es un editor de dibujo ni un tema de Mermaid (tt-a1i, 2026a).

Límites

No parsea Mermaid, no hace auto-layout genérico, no hospeda el mapa ni ofrece un editor visual (tt-a1i, 2026a). No inspecciona infraestructura en ejecución. El comando guide sugiere el tipo de diagrama, pero no lo dibuja (tt-a1i, 2026b). Hay cinco tipos, y cada uno responde una pregunta distinta (tt-a1i, 2026a):

• architecture: qué hay (servicios, bases, límites).
• workflow: en qué orden ocurre el trabajo (CI, aprobaciones, runbooks).
• sequence: quién llama a quién, y en qué momento (API, caché, autenticación).
• data flow: cómo se mueve el dato (origen, transformación, destino).
• lifecycle: en qué estado está algo (reintentos, esperas, finales).

Si se pide architecture para una secuencia de llamadas, el dibujo puede estar bien y aun así no responder la pregunta.

Para un esquema de diez minutos, Mermaid en el chat alcanza. Si se pide “toda la plataforma”, el mapa omite o deja de leerse.

En conclusión

Archify sirve cuando el diagrama va a vivir en el repositorio, no solo en el chat. Da un JSON que se valida y un HTML que se abre sin servidor. Para muchos reviews de arquitectura con agentes, puede ser la pieza que faltaba.

Pero la pregunta correcta no es si el mapa quedó lindo. Es si alguien puede revisar cada flecha contra una fuente. Gonzáles (2026) lo resume así: “cuando una herramienta puede producir una implementación plausible casi de inmediato, el cuello de botella deja de ser la escritura y pasa a ser la validación” (sección “Por que ahora importa más que antes”).

Responder eso con criterio de ingeniería, y no con un PNG convincente, es el tipo de desafío que en Kranio nos encanta resolver junto a nuestros clientes.

¿Está evaluando diagramas con agentes en su equipo?

En Kranio acompañamos a equipos que ya usan asistentes y necesitan que el artefacto se pueda auditar. La documentación de Archify está en tt-a1i.github.io/archify (tt-a1i, 2026a). Si quiere conversar cómo aplicar esto en su organización, hablemos.

Referencias

• Bizagi. (s.f.). Free: Getting started with Bizagi Modeler. En Bizagi Modeler help. <https://help.bizagi.com/platform/en/freegettingstarted_with.htm>
• Bizagi. (2023, 27 de noviembre). Standards compatability. En Bizagi Modeler help. <https://help.bizagi.com/platform/en/intro_standards.htm>
• Gonzáles, P. (2026, 1 de junio). Spec-driven coding con IA: guia practica para equipos. Kranio. <https://www.kranio.io/blog/spec-driven-coding-con-ia-guia-practica-para-equipos>
• tt-a1i. (2026a). Archify [Software]. GitHub. <https://github.com/tt-a1i/archify>
• tt-a1i. (2026b). Authoring cookbook. En Archify. GitHub. <https://github.com/tt-a1i/archify/blob/main/docs/authoring-cookbook.md>
• Structurizr. (s.f.). Structurizr [Software]. GitHub. <https://github.com/structurizr/structurizr>