How to Iterate on Diagrams via Chat with Targeted JSON IR Edits in Archify

Archify enables chat-driven diagram iteration by accepting JSON patches that are merged into a stored Intermediate Representation (IR), validated against type-specific schemas, and rendered into SVG/HTML for immediate visual feedback.

Archify is an open-source diagramming tool that stores diagram definitions as a JSON-based Intermediate Representation (IR). When working with diagrams via chat, you can send targeted JSON fragments to modify specific nodes, edges, or properties without redrawing the entire diagram, leveraging a modular pipeline that ensures structural integrity and stable visual layout.

Understanding the JSON IR Architecture

Archify's core innovation lies in its schema-validated JSON IR. Each diagram type—whether workflow, sequence, architecture, or dataflow—has a dedicated schema definition located under archify/schemas/. These JSON Schema files (such as archify/schemas/workflow.schema.json and archify/schemas/architecture.schema.json) define required fields, allowed values, and default parameters for their respective diagram types.

This architectural choice guarantees that any partial JSON sent through the chat interface still conforms to the overall diagram contract. When you submit a fragment containing only the fields you want to change, the system fills missing fields from schema defaults, ensuring the merged IR remains valid without requiring you to resend the entire diagram definition.

The Five-Step Iteration Pipeline

When a chat user submits a JSON edit, Archify executes a consistent five-step flow. This pipeline is orchestrated through archify/bin/archify.mjs, which serves as the unified entry point for both CLI usage and chat-driven tool calls.

1. Parse the Incoming Fragment

The pipeline begins by parsing the incoming JSON payload. The entry point at archify/bin/archify.mjs handles command-line arguments or raw JSON payloads, preparing the data for processing.

2. Load the Base IR

Archify retrieves the existing diagram state, either from a stored file or a default template. Example templates are available in archify/examples/, such as archify/examples/agent-tool-call.workflow.json, which provides a complete starting structure that users can copy and modify.

3. Merge with Deep-Merge Semantics

The system performs a deep merge of the incoming fragment into the base IR. This preserves untouched sections of the diagram while updating only the specified fields. Because the merge operates at the field level, incremental edits do not cause unchanged nodes or edges to lose their positional or styling data.

4. Validate Against Schema

The merged IR is passed to archify/renderers/shared/validator.mjs, which runs JSON Schema validation against the appropriate type definition. This step rejects malformed patches early, returning specific error messages to the chat user before rendering begins. The validator ensures that node references in edges actually exist and that all required fields are present.

5. Render to Visual Output

Finally, the validated IR is handed to the appropriate renderer module in archify/renderers/<type>/. For example, archify/renderers/workflow/render-workflow.mjs converts workflow IR into SVG/HTML. Because renderers work on the final IR state, only changed sections trigger re-computation. The renderers implement orthogonal routing and lane/column concepts that maintain stable layouts even as nodes and edges are added or removed.

Practical Examples of Targeted JSON Edits

Updating a Workflow Node

To modify an existing node, send a JSON fragment containing the node's id and the fields you wish to update:

{
  "id": "router",
  "label": "Tool Router",
  "sublabel": "select capability",
  "tag": "enhanced routing"
}

When this fragment is processed, Archify merges it into the existing workflow IR (using archify/examples/agent-tool-call.workflow.json as a base if none is stored). The resulting diagram displays the new sublabel and tag without redrawing unchanged elements.

Adding a New Edge

You can inject new connections by sending partial edge definitions:

{
  "edges": [
    { "from": "planner", "to": "store", "variant": "emphasis", "label": "cache result" }
  ]
}

The validator checks that the from and to nodes exist in the current IR. Once validated, the renderer routes the edge orthogonally, preserving existing lane boundaries and minimizing layout disruption.

Switching Diagram Types

To change the visualization type while preserving your diagram structure:

{
  "diagram_type": "architecture",
  "nodes": [ 
    { "id": "api", "label": "API Gateway" }
  ],
  "edges": [ 
    { "from": "client", "to": "api" }
  ]
}

Changing the diagram_type triggers Archify to load the architecture schema and invoke archify/renderers/architecture/render-architecture.mjs. The same merge-validate-render pipeline applies, ensuring consistent behavior across diagram types.

Key Components Enabling Chat-Driven Iteration

• IR Schemas (archify/schemas/*.schema.json): Define the structural contract for each diagram type, enabling safe partial updates through default value injection.

• Validator (archify/renderers/shared/validator.mjs): Centralized JSON Schema validation that runs before rendering, providing immediate feedback on syntax or reference errors.

• Renderers (archify/renderers/<type>/): Modular conversion engines that transform validated IR into visual output. Each implements a render function expecting a fully-formed IR object.

• CLI Entry Point (archify/bin/archify.mjs): Unified interface that parses JSON payloads and coordinates the pipeline, ensuring identical behavior for chat-driven and command-line usage.

Summary

• Archify stores diagrams as JSON IR with strict schema validation under archify/schemas/, enabling targeted edits withoutfull redefinition.
• The iteration pipeline follows five steps: Parse, Load, Merge, Validate, and Render, orchestrated through archify/bin/archify.mjs.
• Deep-merge semantics preserve unmodified sections of the diagram, while orthogonal routing maintains stable visual layouts during incremental changes.
• The modular renderer architecture in archify/renderers/<type>/ allows developers to add new diagram types without modifying core validation or merging logic.

Frequently Asked Questions

What is the Intermediate Representation (IR) in Archify?

The Intermediate Representation is a JSON-based data structure that serves as the single source of truth for diagram definitions. Stored in files like archify/examples/agent-tool-call.workflow.json, the IR captures nodes, edges, layout hints, and metadata in a schema-validated format that is independent of the final rendering output.

How does Archify validate partial JSON edits?

Validation occurs through archify/renderers/shared/validator.mjs, which loads the appropriate JSON Schema from archify/schemas/ and checks the merged IR for structural correctness. The validator ensures that referenced nodes exist, required fields are present, and data types match schema expectations, returning specific error messages for malformed input.

Can I switch diagram types without losing my node definitions?

Yes. By updating the diagram_type field in your JSON payload, Archify switches to the corresponding schema and renderer (such as archify/renderers/architecture/render-architecture.mjs). As long as your nodes conform to the new schema's requirements, the existing node definitions persist through the type transition.

Where are the schema definitions located?

Schema definitions reside in the archify/schemas/ directory. You will find workflow.schema.json for workflow diagrams, architecture.schema.json for architecture diagrams, and additional schema files for other supported diagram types. These files define the valid structure, field types, and default values for each IR variant.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}