Skip to content
Back to Blog
Product Updates

Draw Architecture Where It Is Governed

Shi YanAugust 20, 202610 min read

Ask to see the architecture of almost any system and you will be sent a picture. A PNG in a slide deck, a screenshot in a wiki page, an export attached to an email with "final_v3" in the filename.

The picture is rarely wrong on the day it is made. The trouble starts afterwards. The source file is on one person's laptop. The review that approved the design looked at one version; the team built from another. Six months on, nobody can say which drawing was the one that was agreed, and the reviewer who would know has changed teams.

A diagram is the most-read architecture artefact an organisation produces. It is also the least governed.


A Picture Cannot Be Reviewed

Three things go wrong when a diagram is only an image.

It has no history
Nobody can show what the drawing looked like when it was approved.
It cannot be read
A reviewer, a search, or an AI sees pixels, not components and connections.
It lives elsewhere
The decision is in one tool and its picture is in another.

Figure 1 — Why an exported image is weak evidence of an architecture.

The first is the audit problem. "Show me the design that was reviewed" is a fair question, and an image with no version history cannot answer it.

The second is quieter and matters more each year. An AI architecture review can reason about a system only from what it can read. If the trust boundaries, the data stores and the connections between them exist only as shapes in a bitmap, the review is working from the prose around the picture and missing the picture itself.

The third is ordinary friction. Every time the drawing changes, someone has to export it, upload it, and tell people. Often they do not, and the review record drifts away from the system.


Diagrams, Inside cajeX

cajeX now includes a diagram editor, and from today it is on for every workspace. It is the draw.io editor, hosted by cajeX itself, so the content of your diagrams does not leave the platform.

A diagram in cajeX is an ordinary document. It is a .drawio file in the Documents of a project or an application, and it can be downloaded, renamed, versioned, marked confidential and deleted like any other document. One click opens it in the editor.

A diagram as a picture


  • Source file on a laptop
  • Exported, then uploaded
  • One version, whichever is newest
  • Invisible to search and to AI review
  • Vendor format, or none
becomes

A diagram as a document


  • Stored with its project or application
  • Edited in place
  • Named versions kept
  • Read by search and by AI review
  • Open draw.io format

Figure 2 — What changes when the drawing is a governed document.

Two homes for a drawing

Where a diagram lives says what it is for.

A diagram on a project describes a change: the target state, the migration steps, the before and after. It belongs with the review of that change.

A diagram on an application describes the application as it currently is. It outlives any one project and is what the next team should open first. This fits the way Applications works in cajeX generally: change material stays with the project, and material that describes the system as it now stands moves to the application.

Versions you name

There are two ways to save. Save is for ongoing work. Save as version stores the current canvas as a new version of the document and keeps the earlier ones in its version history.

Use versions for the moments that matter: as reviewed, approved target state, before the migration. When someone asks which drawing the design authority approved in March, the answer is a version you can open, not a memory.

Version 1

First draft

Version 2

As reviewed

Version 3

Approved

Version 4

As built

Shared with the team for comment

What the review session looked at

Findings resolved, target state agreed

Handed to the application at completion

Figure 3 — Named versions give the drawing the same history as the decision.

Small things that prevent lost work

While you draw, cajeX keeps a draft on your device. Close the tab by accident and reopening the diagram offers to restore it.

If a colleague saves the same diagram while you have it open, your save is refused and you are given a choice: load their version, keeping yours in the local draft, or overwrite with yours. Silent last-write-wins is how a week of someone's work disappears, so the editor does not do it.

And you can park a diagram. Minimising the editor keeps the drawing open with its full undo history while you go and read the finding or the requirement you needed. A chip in the top bar brings it back. Up to three diagrams can be parked at once.


The Drawing Becomes Readable

Saving a diagram does more than store a file. cajeX reads its structure, the components, their properties and the connections between them, and turns that into text.

That text goes to two places. It goes into global search, so a search for "ledger" finds the diagrams with a ledger in them. And it goes into AI review: a project's diagrams inform the review of that project, and an application's diagrams inform the review of that application.

You draw
Shapes and connections
→
You save
A .drawio document
→
cajeX reads it
Components, properties, links
→
Search
Finds what is drawn
→
AI review
Reasons about it

Figure 4 — A saved diagram is read as structure, not stored as an image.

The practical effect is that accuracy is rewarded. Draw the database inside the right network zone, label the connection that crosses the boundary, and the review can check your directive about cross-zone traffic against what you actually drew.

Consider a manufacturer adding a cloud analytics service that reads from a plant historian. The directive says nothing in the control network may be reached directly from the enterprise network; traffic goes through the DMZ. In a slide, that is a line someone has to notice. In a cajeX diagram, the historian is a shape in a zone, the analytics service is a shape in another, and the connection between them is something the review can see goes straight across.

The editor ships with cajeX shape libraries for this kind of work: ISA-95 functional levels from L0 to L4, security zones, and generic enterprise shapes, alongside everything draw.io provides.


Asking the Assistant to Draw

With a diagram open, the cajeX assistant can edit it. Ask for what you want in words: add a firewall between the web tier and the database; mark the payment service as critical; route the historian feed through the DMZ.

The assistant does not change the drawing straight away. It proposes the edit as a card, and when you confirm, the change is applied to the open editor only. You look at the result on the canvas, adjust it if you like, and save when you are satisfied. Undo works on it like on any other edit. On a large diagram the edit can take a minute or two.

For technology domains such as AWS, Azure, Google Cloud, Kubernetes and Cisco, the assistant uses the official icon sets by default. Ask for plain shapes if you prefer boxes.

This is the same pattern the assistant follows everywhere in cajeX, described in an assistant that asks before it acts: it proposes, a person decides.

What you askWhat happens
Add"Add a firewall between the web tier and the database"A proposed edit; on confirm, the shape and its connections appear on your canvas
Change"Mark the payment service as critical"The shape's property is set, and it will be read that way by the next review
Re-route"Send the historian feed through the DMZ"The direct connection is replaced by one through the zone you named
SaveNothing. This is yours to doThe assistant never saves; the edit stays unsaved until you save it

Figure 5 — Editing a diagram by asking, with the save left to the person.


For People Who Want the Source

The editor has a Split view that shows the diagram's XML beside the canvas. The two stay in step in both directions: draw, and the XML updates; edit the XML, and the canvas follows shortly after you stop typing. Invalid XML never reaches the canvas; the panel says what is wrong and the drawing keeps its last valid state.

Selection follows too. Click a shape and the XML scrolls to its definition. Click inside a shape's XML and the canvas selects it.

Most people will never open this. For the few who want to change a property on forty shapes at once, or paste a fragment from one diagram into another, it turns a tedious hour into a minute.


Open Format, On Purpose

We could have built a proprietary canvas. We chose draw.io because the format is open and widely used. A .drawio file downloaded from cajeX opens in the desktop draw.io application, and a file made there can be uploaded and opened in cajeX.

That matters for the same reason directives are plain, readable statements rather than something locked inside a tool. The architecture is yours. A governance platform should make it easier to hold on to, not harder to leave with.

2 MB

of diagram XML per file, which is thousands of shapes

3

diagrams can be parked at once while you work elsewhere

.drawio

an open format you can download and open anywhere

Figure 6 — The practical limits, and the format.


Getting Started

Open any project, go to its Documents, and choose New Diagram. Name it and the editor opens on a blank canvas. If your workspace has Applications turned on, the same button is on each application's Documents tab.

If you already have draw.io files, upload them as documents. Each one gains an Open in diagram editor action.

The editor is built for a desktop screen. On a phone, download the document to view it.

Then do one thing differently at your next review. Instead of attaching an exported image, open the diagram, save it as a version called "as reviewed", and run the review. The drawing the reviewers saw, the findings it produced, and the version that was eventually approved will all be in one place, in order, where the next person can find them.

For everything else in the workspace, see the product overview.

Ready to transform your architecture governance?

cajeX brings AI-powered reviews, knowledge management, and directive lifecycle management to your enterprise architecture team.