CubeLabs

1. Qué es Archify y por qué "diagramas verificables"

Archify es un sistema de renderizado y validación escrito en Node.js que se entrega como Agent Skill: lo usas pidiéndole a tu agente de IA que dibuje un sistema, y el agente genera una especificación JSON IR tipada que Archify compila de forma determinista a un archivo HTML autocontenido con SVG interactivo. El resultado no es un mockup: es un artefacto que se puede abrir, explorar, exportar y compartir.

El caso de uso central es la comunicación de arquitectura: "turn a codebase or system description into a polished, interactive system map — directly in chat". Puedes partir de una descripción en lenguaje natural sin repositorio, o pedir evidencia real abriendo un repositorio para que el diagrama refleje el código.

El nombre de la marca resume su tesis: verificación. Cada diagrama pasa checks atómicos (esquema, layout, HTML/SVG, rutas y solapamientos) antes de que un artefacto "showcase" reemplace al último bueno conocido. Si algo falla, recibes un recibo de reparación con código de regla estable y correcciones soportadas, no un stack trace de Node.

2. Instalación en tu agente paso a paso

Archify se instala como skill en el agente que ya usas. La forma estándar usa el instalador de skills de npm:

$ npx skills add tt-a1i/archify -g

Para una instalación explícita y no interactiva en Cursor:

$ npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

Para probar sin instalar nada, con Codex CLI:

$ npx skills use tt-a1i/archify@archify --agent codex

$ cd archify
$ node bin/archify.mjs doctor
$ node bin/archify.mjs demo /tmp/archify-demo   # genera un ejemplo de referencia

3. Primer mapa sin repositorio: de la frase al diagrama

El camino rápido no requiere clonar nada: describes el sistema en el chat y el agente hace el resto. Ejemplo mínimo:

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

Para un diagrama con criterio de arquitectura, da alcance, componentes y un camino principal. Un prompt que funciona bien:

> Analyze this repository, then use archify to create a high-level
> runtime architecture diagram. Show 8-12 core components, one primary
> path, external dependencies, and trust boundaries.
> Put supporting detail in cards instead of adding more edges.

Después iteras en el propio chat con peticiones quirúrgicas: "add Redis", "move auth to the left", "highlight the rollback path". Archify conserva el JSON fuente tipado para que los cambios no desbaraten la estructura ya validada.

4. El contrato JSON IR tipado

Todo renderizado con Archify parte de una especificación con esquema: JSON IR (Intermediate Representation). El agente la escribe a partir de tu descripción; tú normalmente no la tocas a mano, pero entenderla te da control sobre la calidad.

Estructura mínima de un fuente: schema_version, diagram_type, meta.title y los arrays estructurales del renderer (nodos y relaciones). El perfil de calidad vive en meta.quality_profile: standard para explorar y showcase para un artefacto pulido o una prueba "checked-in". Un fragmento ilustrativo (consulta archify/schemas/ para los campos exactos):

{
  "schema_version": 2,
  "diagram_type": "architecture",
  "meta": {
    "title": "Web App con caché Redis",
    "quality_profile": "showcase"
  },
  "nodes": [
    { "id": "browser", "type": "frontend", "label": "Browser" },
    { "id": "api", "type": "backend", "label": "API Server" },
    { "id": "cache", "type": "database", "label": "Redis" },
    { "id": "db", "type": "database", "label": "PostgreSQL" }
  ],
  "relationships": [
    { "from": "browser", "to": "api", "label": "HTTPS" },
    { "from": "api", "to": "cache", "label": "cache read" },
    { "from": "api", "to": "db", "label": "fallback query" }
  ]
}

Las variants (default, emphasis, security, dashed) matizan visualmente nodos del mismo tipo. Las etiquetas de relación son datos semánticos: no se borran para "arreglar" la geometría; se mueven o se acortan conservando el significado (protocolo, acción, dirección, sincronía).

5. Los 5 tipos de diagrama y el escenario guide

Archify tiene cinco renderers, cada uno con su esquema, su ejemplo checked-in y sus invariantes de layout:

¿No sabes cuál elegir? Pregunta al guía de escenarios, una utilidad CLI sin dependencias que recomienda tipo y devuelve una receta (no dibuja por ti):

$ node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
$ node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Archify también acepta Mermaid como entrada — pero como intención, no como estilo: lee la topología y re-autoriza JSON fresco. Los flowchart/graph se mapean a workflow (o architecture si es un mapa de componentes); los sequenceDiagram a sequence; los stateDiagram a lifecycle.

6. Ciclo de autoría: generate → validate → preview → deliver

El flujo de trabajo de Archify es un pipeline explícito con cinco etapas. Cada una tiene su comando y su contrato:

Los comandos clave, ejecutados desde el directorio archify/:

$ node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
$ node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
$ node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

preview es un modo de escritorio explícito y solo-loopback: observa un JSON en un puerto aleatorio de 127.0.0.1, mantiene la última salida verificada ante fallos, termina con Ctrl-C y no añade runtime al HTML generado. Usa --no-open para tests o apertura manual. deliver --open es una entrega one-shot opt-in tras el commit: si el opener falla, el éxito no se pierde — el JSON queda en stdout y la ruta absoluta alternativa en stderr.

7. Validación y recibos de reparación legibles

Archify separa la validación mecánica de la opinión estética: el CLI te da recibos JSON con reglas estables, y la revisión visual final es tuya (o de un revisor con imagen).

Con --json, validate y deliver emiten un único objeto JSON. En éxito, el recibo contiene los artifact checks y el resumen de composición. Un pase showcase exige los 9 checks de artefacto con 0 errores de composición y 0 warnings (un recibo con solo 4 checks es validación básica, nunca aceptación showcase).

En fallo, el recibo incluye un stage y un array diagnostics[]. Cada diagnóstico nombra el subject exacto, la evidence medida y solo los supportedFixes permitidos — sin stack traces de Node ni intentos de reparación a ciegas.

8. Revisar arquitectura antes del merge: Architecture Delta

Uno de los superpoderes de Archify es revisar cambios de arquitectura antes de fusionarlos: compara dos instantáneas validadas como Before / Delta / After, con un recibo en máquina que lista hechos exactos añadidos, eliminados, modificados, movidos y reruteados.

$ node bin/archify.mjs compare architecture base.json head.json \
    architecture-delta.html --quality showcase --json

El comando escribe el HTML y un recibo sidecar a su lado. Es ideal para la review de PRs: seleccionas un cambio autorado (o reproduces una revisión finita solo-viewer) y el diagrama muestra qué hechos de topología cambian — sin inferir impacto, riesgo ni seguridad de merge. Para diagramas de despliegue en producción, el perfil deployment-ownership falla cerrado (fail-closed) cuando faltan propietarios autorados, colocación regional, alcance de bases de datos privadas o cruces nombrados: nunca es implícito y no inspecciona infraestructura viva.

9. Explorar, presentar y exportar el artefacto

El HTML generado incluye de serie un visor de escritorio autocontenido: cambio de tema, pan/zoom, búsqueda, focus, trazado de relaciones, vistas semánticas, presentación y exportaciones veraces. No es trabajo extra de autoría — son capacidades del lector.

Atajos principales del visor:

Los enlaces estables restauran estado: #focus=<id>, #focus=<id>&reach=upstream|downstream, #relation=<id>, #route=<source>~<target>, #lens=<kind>~<kind> y #view=<view-id>. La animación dirigida por el lector es finita, respeta prefers-reduced-motion y nunca entra en las exportaciones canónicas.

El menú Export copia PNG al portapapeles y descarga formatos estáticos o con movimiento: PNG, SVG, WebM y HTML autocontenido. Copy Share Card genera la imagen canónica 1200×630 para README, releases o redes; tras trazar una ruta, Export → Route Share Card descarga ese camino exacto como PNG 1200×630 con el diagrama completo como contexto; y tras trazar reach, Reach Share Card captura esa lectura sin afirmar impacto en runtime.

El estilo visual se controla con meta.visual_preset (signal-flow, blueprint, classic, editorial) y el tema (dark/light) es independiente del preset: cambiar Light/Dark preserva el preset actual. meta.locale (en | zh-CN) localiza solo la UI del visor; el contenido autorado nunca se traduce automáticamente.

10. Evidencia desde repositorios reales y límites honestos

Cuando el diagrama debe reflejar código real, Archify puede anclar nodos a evidencia de repositorio: los nodos Evidence-backed se marcan como SRC n y abren archivos y rangos de líneas verificados por Git, fijados a un commit público. Se añade metadatos del repositorio (origin, commit, blobs, líneas solicitadas) al JSON y se pasa la ruta local:

$ node bin/archify.mjs validate architecture path/to/diagram.json \
    --repo-root path/to/repository --quality showcase --json

Archify verifica origin, commit, blobs y líneas: no añadas evidencia fuente cuando el repositorio o la revisión no se puedan verificar. Los artefactos ordinarios se quedan sin evidencia; esta es opt-in y solo cuando la pides.

Para identidad de producto, Archify incluye marcas oficiales (brand marks). Si el nodo nombra un producto real con marca integrada, se pone su ID canónico en brand; si no existe preset y aportas la URL oficial, node bin/archify.mjs brands capture "<url>" --json captura el objeto con digest-pinning. Render y validate nunca hacen una captura sin pin. Y no se infiere una marca de un rol vago como "database": el type, la etiqueta y la relación son los hechos semánticos.

Por último, los límites explícitos del proyecto (léelos antes de prometer algo a tu equipo):

• No es un editor WYSIWYG ni una herramienta de dibujo generalista.
• No es un theme de Mermaid ni un motor de auto-layout genérico (aunque acepta Mermaid como entrada y la re-autoriza).
• No tiene hosting compartido de diagramas: el artefacto es un archivo HTML que tú distribuyes.
• El perfil deployment-ownership no inspecciona infraestructura viva; trabaja solo con hechos autorados.
• El visual-check mide comportamiento acotado en navegador; la aprobación perceptual final requiere un humano.