Cómo hacer la tuya con el motor

Objetivo

Producir para un proyecto tuyo una página de arquitectura viva y su manifiesto, de modo que tools/import-arquitecturas.py --check <repo> termine con código 0 y la página pueda publicarse en /arquitecturas/.

Por qué

El motor (ArqViva) no dibuja a mano: lee datos. Si los datos son verdaderos, la página es verdadera; si inventas una flecha, el diagrama miente con la misma elegancia. Por eso el trabajo importante es la investigación, no el dibujo.

Pasos

1. Investiga y escribe docs/arquitectura.notas.md. Recorre el repo y responde: actores, contenedores (cada pieza que se despliega por separado, con su tecnología y la máquina donde corre), llamadas reales entre ellos (protocolo y qué viaja), de 3 a 6 flujos, datos y despliegue. Si algo no existe, anota “no aplica” y omite esa vista. Lo que no esté en el código se marca “por confirmar” y no se dibuja.
2. Copia la plantilla. Copia shared/arquitectura-viva/plantilla-arquitectura.html a docs/arquitectura.html de tu repo. Cambia solo textos y datos: el CSS y el JavaScript del motor no se tocan. Borra la pestaña y la sección de las vistas que no apliquen.
3. Rellena N. Un objeto por contenedor sobre un lienzo de 1200×690: x, y, w, h, kind, ttl, tech, color (blue propio, violet de otro repo, amber externo), ext: true si existe fuera del proyecto, resp y kv. Evita los ids usr, wrk y api: la plantilla los usa para sus pastillas.
4. Rellena E. Cada llamada lleva id, a, b, as, bs, l, y ay/by para desplazar el anclaje. Un id de llamada no puede coincidir con un id de nodo.
5. Rellena FLOWS. Un flujo es {id, t, steps}. Un paso ["e1","texto"] es la llamada; con {rev:true} es la respuesta; ["srv","texto"] es un paso interno de una caja; {note:"texto", over:["web","srv"]} es una nota. Añade STATES solo si el proyecto tiene una máquina de estados, y TABLES/REL solo si guarda datos.
6. Escribe docs/arquitectura.json. Campos: schema: 1, slug en kebab-case, name y oneLiner con es y en no vacíos, machines (solo etiquetas genéricas como “PC Windows”, “Mac mini”, “Hostinger”, “GitHub”), containers, calls y flows (deben igualar lo que declara la página), views, hasCore, updated (AAAA-MM-DD), status y landing con order y projectSlug. Empieza en draft; cambia a done solo después de abrir la página y comprobar cajas y flujos. Borra la clave _reglas del ejemplo.
7. Valida. ArqViva.validate imprime en rojo, en la página, cada id inexistente que encuentre. Corrígelos todos.
8. Pasa el importador. python tools/import-arquitecturas.py --check <repo> valida el manifiesto, el grafo y los conteos sin escribir nada, y audita privacidad.

Ejemplo mínimo con 3 nodos, 2 llamadas y 1 flujo:

const N = {
  web:   {x:40,  y:250, w:200, h:100, kind:"navegador", ttl:"Página", tech:"HTML + JS", color:"blue",
          resp:"Envía la consulta y pinta el resultado.", kv:{"Corre en":"Navegador del usuario"}},
  srv:   {x:480, y:250, w:220, h:100, kind:"servicio", ttl:"Servicio", tech:"Python", color:"blue",
          resp:"Valida la consulta y lee el almacén.", kv:{"Entrada":"JSON","Salida":"JSON"}},
  store: {x:920, y:250, w:220, h:100, kind:"archivos", ttl:"Almacén", tech:"JSON en disco", color:"amber", ext:true,
          resp:"Guarda los datos de referencia.", kv:{"Sin base de datos":"archivos de texto"}},
};
const E = [
  {id:"e1", a:"web", b:"srv",   as:"r", bs:"l", l:"POST /buscar", ay:0, by:0},
  {id:"e2", a:"srv", b:"store", as:"r", bs:"l", l:"lee datos.json", ay:0, by:0},
];
const FLOWS = [
  {id:"buscar", t:"Buscar un dato", steps:[
    ["e1", "La página envía la consulta"],
    ["srv", "Valida el texto recibido"],
    ["e2", "Lee el archivo de datos"],
    {note:"Sin base de datos: todo es lectura de archivos", over:["srv","store"]},
    ["e1", "Devuelve el resultado en JSON", {rev:true}],
  ]},
];

Qué salió mal de verdad

La primera versión del manual indicaba escribir las secuencias como bloques Mermaid. Un sequenceDiagram falló con “Syntax error in text” porque un mensaje llevaba un punto y coma. Ese manual conserva aún esa mención; el motor desde el 2026-10-11 no usa Mermaid ni CDN, y el importador rechaza cualquier pre.mermaid. Ante una duda, manda SCHEMA.md. Además, el importador falla en seco ante hallazgos de privacidad: sale con código 1 y no escribe nada, con el archivo y la línea de cada hallazgo.

Cómo verificar

• Abre docs/arquitectura.html en el navegador: cada caja responde al clic y cada flujo se reproduce sin errores en rojo.
• Ejecuta python tools/import-arquitecturas.py --check <repo>. Un código 0 significa válido y sin hallazgos; 1, hallazgos de privacidad o de texto público; 2, manifiesto o página inválidos (esquema, conteos, un paso o llamada que apunta a la nada).
• Regla de privacidad: ninguna IP, nombre de host, ruta personal, correo ni credencial en la página, el manifiesto ni las notas.

Autoevaluación

1. ¿Por qué el trabajo central es la investigación y no el dibujo?
2. ¿Qué tres cosas deben coincidir entre el manifiesto y la página?
3. ¿Qué diferencia hay entre ["e1","texto"] y ["e1","texto",{rev:true}]?
4. ¿Qué significan los códigos de salida 0, 1 y 2 del importador?
5. ¿Qué ids de nodo conviene evitar y por qué?