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

> Iterate on diagrams using chat with Archify. Make targeted JSON IR edits for instant visual feedback and streamlined diagram updates.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json) and [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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:

```json
{
  "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:

```json
{
  "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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/workflow.schema.json) for workflow diagrams, [`architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/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.