How to make yours with the engine

Goal

Produce a living-architecture page and its manifest for a project of yours, so that tools/import-arquitecturas.py --check <repo> exits 0 and the page can be published under /arquitecturas/.

Why

The engine (ArqViva) does not draw by hand: it reads data. If the data is true, the page is true; if you invent an arrow, the diagram lies just as elegantly. So the real work is the research, not the drawing.

Steps

1. Research and write docs/arquitectura.notas.md. Walk the repo and answer: actors, containers (every piece deployed on its own, with its technology and the machine it runs on), the real calls between them (protocol and payload), 3 to 6 flows, data and deployment. If something does not exist, write “no aplica” and skip that view. Anything the code does not show is marked “por confirmar” and not drawn.
2. Copy the template. Copy shared/arquitectura-viva/plantilla-arquitectura.html to your repo’s docs/arquitectura.html. Change only text and data: the engine’s CSS and JavaScript stay untouched. Delete the tab and section of any view that does not apply.
3. Fill N. One object per container on a 1200×690 canvas: x, y, w, h, kind, ttl, tech, color (blue own, violet from another repo, amber external), ext: true if it exists outside the project, resp and kv. Avoid the ids usr, wrk and api: the template uses them for its own pills.
4. Fill E. Each call has id, a, b, as, bs, l, plus ay/by to shift the anchor point. A call id must not collide with a node id.
5. Fill FLOWS. A flow is {id, t, steps}. A step ["e1","text"] is the call; with {rev:true} it is the reply; ["srv","text"] is an internal step of one box; {note:"text", over:["web","srv"]} is a note. Add STATES only if the project has a state machine, and TABLES/REL only if it stores data.
6. Write docs/arquitectura.json. Fields: schema: 1, a kebab-case slug, name and oneLiner with non-empty es and en, machines (generic labels only, such as “PC Windows”, “Mac mini”, “Hostinger”, “GitHub”), containers, calls and flows (they must equal what the page declares), views, hasCore, updated (YYYY-MM-DD), status and landing with order and projectSlug. Start at draft; switch to done only after opening the page and checking boxes and flows. Delete the example’s _reglas key.
7. Validate. ArqViva.validate prints, in red on the page, every id that points nowhere. Fix them all.
8. Run the importer. python tools/import-arquitecturas.py --check <repo> validates the manifest, the graph and the counts without writing anything, and audits privacy.

A minimal example with 3 nodes, 2 calls and 1 flow:

const N = {
  web:   {x:40,  y:250, w:200, h:100, kind:"browser", ttl:"Page", tech:"HTML + JS", color:"blue",
          resp:"Sends the query and renders the result.", kv:{"Runs on":"User's browser"}},
  srv:   {x:480, y:250, w:220, h:100, kind:"service", ttl:"Service", tech:"Python", color:"blue",
          resp:"Validates the query and reads the store.", kv:{"Input":"JSON","Output":"JSON"}},
  store: {x:920, y:250, w:220, h:100, kind:"files", ttl:"Store", tech:"JSON on disk", color:"amber", ext:true,
          resp:"Holds the reference data.", kv:{"No database":"plain text files"}},
};
const E = [
  {id:"e1", a:"web", b:"srv",   as:"r", bs:"l", l:"POST /search", ay:0, by:0},
  {id:"e2", a:"srv", b:"store", as:"r", bs:"l", l:"reads data.json", ay:0, by:0},
];
const FLOWS = [
  {id:"search", t:"Look something up", steps:[
    ["e1", "The page sends the query"],
    ["srv", "Validates the received text"],
    ["e2", "Reads the data file"],
    {note:"No database: everything is a file read", over:["srv","store"]},
    ["e1", "Returns the result as JSON", {rev:true}],
  ]},
];

What actually went wrong

The first version of the manual told authors to write sequences as Mermaid blocks. A sequenceDiagram failed with “Syntax error in text” because one message contained a semicolon. That manual still carries the Mermaid mention; since 2026-10-11 the engine uses no Mermaid and no CDN, and the importer rejects any pre.mermaid. When in doubt, SCHEMA.md wins. The importer also fails hard on privacy hits: it exits with code 1 and writes nothing, printing the file and line of each hit.

How to verify

• Open docs/arquitectura.html in a browser: every box responds to a click and every flow replays with no red errors.
• Run python tools/import-arquitecturas.py --check <repo>. Exit 0 means valid with no hits; 1 means privacy or public-copy hits; 2 means an invalid manifest or page (schema, counts, a step or call pointing nowhere).
• Privacy rule: no IP address, host name, personal path, email or credential in the page, the manifest or the notes.

Self-check

1. Why is the research, not the drawing, the central work?
2. Which three things must match between the manifest and the page?
3. What is the difference between ["e1","text"] and ["e1","text",{rev:true}]?
4. What do the importer’s exit codes 0, 1 and 2 mean?
5. Which node ids should you avoid, and why?