The Canonical Model Pattern: A Neutral Core Between Tools, Canvas and AI

Give two people two different ways to edit the same architecture — a canvas and an AI assistant — and you have created a synchronization problem before anyone has drawn a single box. Either one of the two is second-class, kept alive by exporters and importers that quietly lose information, or both write to one place, and someone has to design what that place is. The canonical model pattern is the answer to that second option: a neutral, tool-agnostic core that the canvas and the AI assistant both read from and write to, so that no matter which surface you used this morning, the model itself is the only thing that's actually true.

This isn't a new idea in software generally — it's the same instinct behind a database with multiple client applications, or a document with multiple editors syncing through operational transforms. What's specific to architecture tooling is what the canonical model has to hold to make two very different editing experiences behave as one: stable identity, a small set of well-defined object types, a validation boundary that every write passes through, and a serialization format that survives being exported, edited elsewhere, and imported back without silently losing what it doesn't recognize. Get any of those wrong and the two editing surfaces stop being two views on one truth and become two sources of drift.

The problem that shows up the moment you add a second editor

A single-editor tool never has to solve this. If a canvas is the only way to change an architecture, the canvas's internal representation is the model, by definition — there's nothing else for it to disagree with. The trouble starts the moment a second, genuinely independent editing surface enters the picture, because now there are two candidate sources of truth, and something has to decide which one wins when they disagree.

Most tools that offer a scripting or automation layer alongside a canvas resolve this by making one of them primary and the other a thin, lossy projection. A jArchi script or an EA Add-In can read and write the repository, but the "real" editing experience is still the diagram; the automation layer is an escape hatch for power users, not something the tool's own guarantees were designed around. That shows up in a specific and familiar way: a bulk change made through the scripting layer routinely bypasses checks that a canvas edit would have been subject to, because those checks live in the editor rather than in the repository. The repository accepts whatever the script hands it, and the inconsistency is discovered weeks later by a human reading a view that no longer makes sense.

Add an AI assistant — a surface that edits architecture from a plain-language instruction — and the asymmetry gets worse, not better, if there isn't already a neutral core to target. An assistant that edits "the diagram" is manipulating shapes and coordinates: it can move a rectangle and change a label, but it has no way of knowing that this rectangle and one on another view are the same application, because at that layer they genuinely aren't. An assistant wired into a scripting API inherits whatever that API happens to expose, including whichever checks it happens to skip. Neither arrangement is actually reasoning about elements, relationships, and rules as first-class things, because neither surface was built to be a semantic target — they were built to be driven by a human with a mouse or a keyboard, not to be a stable interface that any editor, human or otherwise, can safely aim at.

What "canonical" actually has to mean

Calling something a canonical model is easy; making it actually function as one requires a few properties that are easy to state and surprisingly easy to get wrong in the implementation.

Stable identity, independent of display name

Every element — an application, a service, a database, a business capability, an actor — gets a machine ID the moment it's created, and that ID never changes for the life of the element. The name is just a property, editable like any other. This sounds like a minor implementation detail until you consider what happens without it: if an element's identity is its name, then renaming "Payment API" to "Payment Service" is indistinguishable, to anything comparing two snapshots of the model, from deleting "Payment API" and creating an unrelated new element called "Payment Service." Every relationship the old element had looks severed. Every view that referenced it looks broken. A diff tool reports a deletion and an addition instead of a rename. This is precisely the kind of ambiguity a canonical model exists to remove, and it has to be solved at the identity layer — no amount of clever diffing downstream can recover information that was never kept in the first place.

A small, closed set of object kinds

Elements, relationships, views, properties/tags, and rules. That's close to the whole vocabulary. Everything editable in Mooodels — whether you touch it directly on the canvas or through an AI-proposed patch — resolves to an operation on one of these five things: add or update an element, connect or disconnect a relationship, define or modify a view, set a property, or evaluate against a rule. Keeping this set small and closed is what makes it possible for two structurally very different editors to target the same interface without either one needing bespoke knowledge of what the other does. It also puts a hard ceiling on how much surface area new capabilities can add: a feature that can't be expressed as some combination of those five operations is a feature that doesn't belong in the core, and that constraint has saved more design arguments than it has caused.

One validation boundary, no side doors

Every write to the model — regardless of which surface originated it — passes through the same validation: does this relationship type make sense between these two element kinds under the active profile, does this rename collide with an existing element, does this operation violate a hard architecture rule. A canvas drag either produces a valid model operation or it's rejected with feedback at the point of the drag, while the connection is still attached to the cursor rather than after it has been committed and forgotten. An AI-proposed change is validated identically, once before a human ever sees it for approval and again at the moment it's applied, because the model may have moved on between the two. An import from an external repository goes through the same boundary too, which is why a malformed source file surfaces as a list of rejected elements you can read and act on rather than as a model that looks fine and behaves strangely. There is no privileged surface that gets to skip the checks the others are held to.

Two editing surfaces, one write path

The point of the pattern isn't that the canvas and the assistant are interchangeable — they're good at different things and architects reach for them for different reasons. The canvas is where you go when the shape of the answer is spatial and you want to think with your hands; the assistant is where you go when the change is tedious, repetitive, or easier to say than to draw. The point is that whichever one you reach for, the result is the same kind of change to the same underlying object graph, not a different, incompatible kind of change that has to be reconciled later.

Take a concrete case: renaming "Customer API" to "Customer Service" and adding a new dependency on an Identity service.

On the canvas, you double-click the element, edit its label, drag a new connection from it to the Identity service box, and pick a relationship type from a short list the active profile allows. Under the hood, that sequence produces exactly two operations: an update to the element's name property, and a connect operation creating a new relationship of the chosen type between two stable IDs. Notice what it does not produce. It doesn't create a second "Customer Service" alongside the old element, because the rename addressed an ID rather than a label. It doesn't record the new arrow as a property of this particular view, because relationships belong to the model and views merely reference them — open a different view containing both elements tomorrow and the dependency is already there, whether or not anyone remembered to draw it twice. And the x/y position you dropped the box at is stored as view geometry, deliberately outside the semantic layer, so that moving a box to make a diagram readable can never be mistaken for changing what the architecture says.

The list of relationship types you were offered is worth pausing on as well, because it is the validation boundary showing up in the interface rather than in an error message. The profile in force knows which relationship kinds are legal between an application and a service, so the picker offers those and nothing else. A rule that would be violated by the connection — a cross-domain dependency that governance requires to go through an integration layer, say — refuses the drop and says why, at the moment your hand is still on the mouse. This is the same check that will run on every other write for the rest of the model's life; it simply happens to be rendered as a menu here.

Through the AI assistant, you'd type something like "rename Customer API to Customer Service and have it authenticate against the identity service." The assistant doesn't touch the model. It proposes a ModelPatch — a small, structured, human-readable list of operations, in this case a rename and a connect, referencing the same stable IDs — and that patch sits in front of you for approval before anything commits. You see exactly what would change, the same way you'd see a diff before merging a pull request, and you can accept it, adjust it, or reject it outright. If you accept it, what lands in the model is the identical pair of operations the canvas would have produced: same IDs, same relationship type, same validation already passed. Diff the model before and after, and there is nothing in the result that says which surface the architect used.

Why AI gets a narrower door than the canvas

The canvas commits directly, subject to validation. AI does not, and that's a deliberate asymmetry, not an oversight. A canvas drag is authored by a person who can see exactly what they dragged; the scope of the change is self-evident from the input, and it is bounded by how much a human can physically do in one gesture. A plain-language instruction is not self-evident in the same way — "clean up the integration domain" could reasonably expand into two operations or twenty, and the gap between what was said and what would happen is exactly the gap where trust breaks if there's no checkpoint.

So the AI path always terminates in a ModelPatch, never a commit. The patch is a list of typed operations — add, update, rename, delete, connect, disconnect — each one referencing stable IDs, each one individually reviewable. It goes through the same validation the canvas path goes through, so a patch that would violate a rule (say, a direct relationship between two domains where governance requires an intermediary) gets flagged before you even see it as something to approve, not after you've committed it and a linter catches it later. What's left for the human is a review, not a leap of faith: read the proposed operations, check them against what you actually meant, approve the ones that match and edit or discard the ones that don't.

The reviewability is a property of the patch format, not of anyone's good intentions. Because every operation names an ID and an operation kind rather than describing an outcome in prose, a patch of forty operations can be read as forty independent claims — this element gets this property, this relationship connects these two things — and each one can be judged on its own. A summary that said "tidied up the integration domain" would be unreviewable at any length. Forty typed operations are tedious to read and completely unambiguous, and tedious-but-unambiguous is the correct trade for a change that is about to become the organization's record of how its systems fit together.

This also means the AI assistant is provider-neutral by design rather than by afterthought. Because its entire output surface is a structured patch validated against the same rules regardless of source, swapping which AI provider generates that patch — a hosted model, a different vendor, an Azure-hosted deployment, a private or sovereign endpoint, or no AI at all — doesn't change what the model does with it. For a public-sector client evaluating where their architecture data is allowed to be processed, that separation between "which AI proposes changes" and "what happens once a change is proposed" tends to be the difference between a workable procurement conversation and a blocked one.

Interoperability without a lossy round trip

A canonical model that only has to satisfy its own editing surfaces is only half the job. Most architects evaluating a new tool already have years of work sitting in Archi or Sparx Enterprise Architect, and nobody serious is going to throw that away to adopt something new. The pattern has to extend outward to those tools too, and the same identity discipline that makes the canvas and the assistant coherent with each other is what makes that round trip survivable.

The practical failure mode with most import/export bridges is silent data loss on the way back out. You import an EA repository, work on it somewhere else, export it back, and discover that EA-specific metadata — GUIDs the original repository used internally, folder structure, diagram geometry the tool doesn't have a concept for — got dropped, because the exchange only round-trips what the second tool understands. The fix isn't to model everything EA or Archi can represent; it's to carry forward what isn't understood as opaque, preserved data attached to the element it came from, rather than discarding it. An element imported from Sparx keeps its original EA GUID as a source mapping, sitting alongside its own stable ID, even while every operation inside the tool addresses it by the new ID. When it's exported back, that original GUID goes with it, and the diagram geometry, folder placement, and anything else the destination tool didn't need to touch comes back intact rather than reset to a default layout.

This matters most on the second and third round trip, not the first. A one-way export is easy for almost any tool to get right. The real test is: import from Sparx, rename three elements and add a domain, export back to Sparx, and check whether a colleague still working in the original EA repository sees a clean update rather than a pile of orphaned GUIDs and duplicate objects. Stable identity plus preserved source mapping is what keeps that second round trip clean.

Profiles: one core, several metamodels

A canonical model built for one methodology is a canonical model for exactly one customer segment. An architect doing pragmatic solution design with generic boxes and arrows, one doing formal ArchiMate motivation-to-implementation modelling, and one working in a C4-flavored software architecture style are not asking for the same vocabulary, and forcing all three into one hardcoded metamodel means at least two of them are working against the grain of the tool.

The canonical model stays methodology-agnostic at its core — elements, relationships, views, properties, rules — and a pluggable profile is what supplies the specific vocabulary layered on top: which element kinds exist, which relationship types are valid between which kinds, what a view is allowed to show, what the deterministic rules check for. Generic, ArchiMate, and C4 profiles all sit on the same core, which is what makes it possible for a Sparx import (typically ArchiMate-flavored) and a from-scratch C4 diagram to coexist as two views over compatible, if not identical, models, rather than requiring two separate tools that can't talk to each other.

Reading the model back: queries, rules and graph analysis

Everything above is about writes. The reason to be this strict about them is that the read side gets dramatically more powerful once you can trust that every element is addressable and every relationship is real, and the read side is where most of the day-to-day value actually lands.

A view, in this pattern, is a stored query rather than a stored picture: which elements to include, which relationships to follow, how many hops out from a starting point, filtered by tag or domain or lifecycle status. That definition is what makes a view cheap. A model holding several thousand elements doesn't get slower to work with, because no view ever asks for all of them; it asks for the forty that answer a particular stakeholder's question. It also makes views self-updating in a way a picture can never be — add a system tagged for a domain, and every view whose query includes that domain contains it the next time it's opened, without anyone remembering to go and redraw anything.

Architecture rules are queries too, run with a different intent. "Every Tier-1 application has a named owner" and "no application in the public zone talks directly to a database in the restricted zone" are both graph predicates evaluated against elements, properties, and relationships. Because they run against the model rather than sampling whichever diagrams happen to exist, a clean result actually means something: there is no fourth undrawn integration hiding outside the sample, because there is no sample. This is the difference between governance as a periodic review meeting and governance as something closer to a build check.

And once the model is a genuine graph, ordinary graph analysis becomes available without anyone building special features for it. Betweenness on the dependency graph finds the integration components that would take the most down with them if they failed. Cycle detection finds the mutual dependencies nobody intended to create, which are usually the result of two correct-looking local decisions made six months apart by different teams. Counting inbound edges finds the elements that are far more load-bearing than their position on any diagram suggests. None of these require a new data model — they require the data model to be honest, which is what the write discipline buys.

Three separate layers of governance, easy to conflate

It's worth being precise about a distinction that gets blurred in casual conversation about "AI-assisted architecture governance," because the three mechanisms behind that phrase behave very differently and fail differently when something's wrong.

Rules are the one layer that's genuinely non-negotiable: they block an invalid write outright, regardless of which surface tried to make it, and they behave identically every time. Linting never blocks anything — it surfaces a list of things worth looking at, the way a code linter flags an unused import without failing the build. AI sits furthest from authority: it can suggest, draft, and propose, but everything it produces is a patch waiting on approval, not a change already made. Collapsing these three into one mental bucket — "the AI enforces our architecture standards" — misdescribes what's actually happening and, worse, invites exactly the kind of unreviewed trust the ModelPatch approval step exists to prevent.

Serialization as a design decision, not an afterthought

How the canonical model is written to disk sounds like the least interesting part of this pattern and turns out to matter a lot for teams that keep architecture in Git alongside their source. A serializer that emits elements in whatever order they happen to sit in memory, or that reformats whitespace differently depending on which path wrote the file, turns a one-line semantic change into a fifty-line diff — which defeats most of the point of having architecture under version control in the first place, since nobody can review a diff that big by eye, and every merge becomes a coin flip.

A canonical model designed for this from the start uses deterministic, stable ordering — elements sorted by ID, relationships grouped predictably, properties emitted in a fixed key order — so that changing one element's description produces a one-line diff, not a reshuffled file. That property isn't free; it has to be designed into the serializer deliberately, because the natural thing for most in-memory structures to do is preserve insertion order or hash order, neither of which is stable across a save and reload cycle by default. Getting this right is what makes it realistic to review an architecture change in a pull request, line by line, rather than treating the model file as an opaque blob only the tool itself can meaningfully compare.

It's worth being clear about what that file is and isn't. It's a serialization: a machine-written record of the object graph, laid out so that a version control system can do useful work with it. Its stability is a property of how the writer emits it, not an invitation to reach in and reorganize it by hand. The review workflow it enables — see the change, discuss it, approve it — is the point, and that workflow sits on top of semantic diffing that understands elements and relationships, not on top of anyone reading raw serialized output for pleasure.

Where the pattern gets genuinely hard

None of this is free, and it's worth naming where a canonical model earns its complexity rather than pretending the pattern has no edges.

Concurrent edits. If two people are editing the same model at the same time — two architects on the canvas, or one on the canvas while a colleague approves a patch that touches the same elements — the canonical core has to resolve concurrent writes the same way any shared document does. Last-write-wins is simple but can silently discard a colleague's change, while proper operational merging is more correct and considerably more work to build, and harder to explain to a user at the moment it produces a merge conflict rather than a clean save. There's no version of this problem that disappears just because the underlying model is well-designed; the model being canonical only guarantees that both edits are operating on the same addressable objects, not that they can't collide.

Profile boundaries. An element that's valid under an ArchiMate profile — say, a formal "Business Service" realized by an "Application Service" — doesn't necessarily have a clean equivalent in a C4 profile's vocabulary. Mixing profiles inside one model, or switching a model's profile after the fact, is exactly the kind of edge case where "pluggable metamodel" stops being a clean abstraction and starts requiring real design decisions about what happens to elements the new profile doesn't have a slot for.

Round-trip fidelity has a ceiling. Preserving unknown metadata as opaque source mapping works well for data the destination tool never needed to touch. It works less well the moment a human edits something the original tool cares deeply about but the canonical model only carries as an opaque blob — an EA-specific stereotype configuration, for instance. The canonical model can preserve what it doesn't understand, but it can't validate changes against rules it was never taught, which is a real limit on how deeply integrated a round trip with any external tool can be without teaching the canonical model more of that tool's own semantics.

Rules are only as good as the modelling underneath them. A deterministic check over the model is exhaustive with respect to the model, which is a genuinely strong guarantee and also a narrower one than it first sounds. A dependency that was never recorded is invisible to every rule, every impact query, and every graph metric, and the tool will report a clean result with total confidence. Linting pushes back on this — orphaned elements and missing properties are exactly the smell of a model that has drifted from reality — but no amount of validation machinery substitutes for someone recording the nightly batch job that reads a database directly. The pattern moves completeness from a search problem to a discipline problem. It does not remove it.

These aren't reasons to abandon the pattern — they're the honest cost side of the ledger, and any tool claiming a canonical model without having thought through concurrent writes, profile boundaries, round-trip ceilings, and the limits of its own validation hasn't actually built one, just described one.

Why this is the right place to spend the complexity

Every one of the hard problems above is hard because the model is real — addressable, mergeable, diffable, subject to rules. That's a strictly better place to have the complexity live than the alternative, which is three or more tools each keeping their own copy of the architecture and drifting apart in ways nobody notices until a decision gets made on stale information. A merge conflict on a canonical model is annoying to resolve. A merge conflict nobody knew existed, because the canvas said one thing and the spreadsheet said another and neither tool had any way of knowing about the other, is worse — it just doesn't announce itself as a conflict at all.

This is the design bet Mooodels makes: put the identity, validation, and serialization work into one neutral core once, accept that the core has real edges — concurrency, profile boundaries, round-trip depth, the honest limits of deterministic checking — and get in exchange a canvas and an AI assistant that can never quietly disagree with each other, because there's only one model for either of them to be right or wrong about. Whichever surface an architect reaches for on a given day, the thing underneath stays the same thing, addressable by the same IDs, checked against the same rules, exportable back to whatever tool the rest of the organization still runs.