Restoring Trust in an Architecture Repository

A repository nobody believed

The organisation, a healthcare provider running several hospital sites, had been modelling in Sparx EA for the better part of seven years when they contacted us. On paper the repository was an asset: thousands of elements, hundreds of diagrams, contributions from every major programme the organisation had run since it was set up. In practice, nobody trusted it. Project architects had quietly gone back to drawing in Visio and pasting screenshots into slide decks, because looking something up in the repository raised more questions than it answered.

The symptoms were familiar to anyone who has inherited a long-lived model. The same clinical application existed three or four times under slightly different names, created by different architects who each searched, failed to find what a colleague had already modelled, and made their own. Stereotypes were applied inconsistently — some elements carried ArchiMate types, some carried UML classes dressed up with a custom stereotype, and a good number carried nothing at all. Relationships existed where a diagram had needed an arrow, and were missing everywhere else, so any attempt at impact analysis returned a picture that was confidently wrong.

What made this engagement different from a modelling exercise is that the problem was as much social as technical. A repository loses trust slowly and regains it even more slowly. Cleaning up the content was the smaller half of the work; the larger half was giving the architecture team reasons to believe the cleanup would hold, so they would come back and model in the repository rather than around it. We agreed with the head of architecture at the start that the goal was not a perfect model. The goal was a repository where a search returns one answer, and where that answer can be relied on in front of a programme board.

Measuring the problem before touching anything

Our first two weeks were spent reading, not editing. We wrote a set of scripts against the Sparx EA automation API that walked the entire repository and produced an assessment we could put numbers behind: how many elements existed per type and stereotype, how many carried no stereotype at all, which names appeared more than once after normalising case, punctuation and the usual suffixes people add, and which elements appeared on no diagram and in no relationship — the orphans that accumulate when diagrams are deleted but their contents are not.

The duplicate detection deserves a word, because exact name matching finds only the easy cases. We matched on normalised names first, then on close variants — the same name with an abbreviation expanded, a version number appended, or a department prefix attached. Every candidate pair went into a spreadsheet, because a script can propose that two elements are the same system but only a person who knows the estate can confirm it. The application manager and the lead architect went through the list together in two half-day sessions, the pairs sorted by match confidence so the doubtful cases got the attention and the obvious ones went quickly. Around one in five candidate pairs turned out to be genuinely different systems with unfortunate names, which is exactly why we never merge on script output alone.

The assessment gave the engagement its shape. Duplication was concentrated where we expected it — the clinical applications that every project touches — and the stereotype problem was concentrated in the oldest packages, modelled before the team had adopted the ArchiMate MDG Technology. Orphaned elements were mostly harmless residue, but a few hundred of them were referenced by document templates, which told us deletion had to be as careful as merging. Just as important, the assessment gave the architecture team something they had not had before: a baseline. Every number we reported at the end of the engagement was a delta against that first report, which is a far more honest way to demonstrate progress than a before-and-after diagram.

Agreeing what one element means

Before merging anything we ran a short series of working sessions to agree the rules that would decide every merge: what makes two elements the same thing, which copy survives, and what happens to the information carried by the copies that do not. It is tempting to treat these as technical questions, but they are policy questions, and answering them ad hoc during a cleanup is how the next generation of inconsistency gets created.

The rules we landed on were deliberately plain. An application element represents a deployed system the organisation operates or subscribes to, named by its common name rather than its procurement name, without version numbers. Environments, instances and modules do not get their own application elements; they are modelled beneath the application or captured in tagged values. Where two elements represented the same system, the survivor was the one with the richest relationship history, not the one with the nicest name — names are cheap to fix, relationships are expensive to rebuild. Every rule was written down in a two-page modelling convention that later became the seed of the team's broader governance approach.

We also agreed what would not be cleaned. The repository contained several packages of project-specific solution models, some for projects long finished. Rewriting history inside those packages would have cost weeks and proved nothing, so they were moved under a clearly named archive branch, excluded from searches and reporting, and left alone — with one deliberate exception: when a shared element was merged, its appearances on archived diagrams were re-pointed along with everything else, so the old views kept rendering against the surviving elements. Drawing that boundary early kept the cleanup focused on the shared landscape model, which is the part people actually query.

Merging duplicates without losing history

Sparx EA has no built-in merge for elements, and it is worth being honest about that limitation because it defines how the work has to be done. Merging two elements means choosing a survivor and then re-pointing everything that referenced the duplicate: connectors, diagram appearances, tagged values worth keeping, and any external references to the element's GUID. Done by hand across hundreds of pairs this is slow and error-prone, so we scripted it against the automation API, with the confirmed spreadsheet from the assessment as the only input the script would accept.

For each confirmed pair the script moved the duplicate's connectors to the survivor unless an identical relationship already existed, re-parented the duplicate's diagram objects so existing diagrams showed the survivor instead, copied tagged values across where the survivor had none and logged conflicting values for a person to arbitrate rather than overwriting either, moved the duplicate's notes, linked documents and owned child elements to the survivor, appended the duplicate's name to an alias list on the survivor so old terminology remained searchable, and only then deleted the duplicate. GUID preservation mattered more than we initially assumed: the organisation's document templates and a handful of external spreadsheets referenced elements by GUID, so the survivor selection took existing references into account, we re-pointed the document templates inside the repository ourselves, and we published a mapping table of retired GUIDs to surviving ones so the owners of external spreadsheets could update theirs.

Because element deletion in Sparx EA is irreversible, every merge wave went through three stages. First a rehearsal against a copy of the production repository, where we reviewed the outcome and tuned the script. Then, after a fresh baseline of the affected packages, against production during an agreed window with the architects out of the model. Then a verification pass: the script logged before-and-after counts of elements, connectors and diagram objects for every package it touched, we reconciled those counts against the confirmed list, and we re-ran the duplicate detection to confirm the wave had removed what it claimed and nothing else. We sized the waves by domain rather than by count, because reviewing a wave is only practical when one person can hold its scope in their head.

We considered, and rejected, the alternative of exporting the repository, restructuring it outside the tool and re-importing it. It looks attractive because the transformation becomes an offline problem, but a round trip through XMI puts diagram layouts and external GUID references at risk unless every transformation is written to preserve them, and it forces a big-bang cutover on a team we were trying to keep working normally. Editing in place through the API, package by package, kept diagrams intact, kept the repository available between waves, and meant that at every point during the engagement there was exactly one repository that was the truth — which, given that the entire problem was people not knowing where the truth lived, was worth more than the elegance of an offline rebuild.

Bringing stereotypes back to one language

With duplicates resolved, the second stream normalised element types and stereotypes to ArchiMate 3, using the MDG Technology the team already had enabled but had never enforced. The older packages held a mixture of plain UML classes, components with home-grown stereotypes like «system» and «app», and ArchiMate elements created from the wrong toolbox profile. To a reader these look similar on a diagram; to a search, a script or the Relationship Matrix they are different populations, which is one of the quieter ways a repository becomes unreliable.

Retyping an element in Sparx EA changes how the tool treats it, so this stream was also scripted, also spreadsheet-driven, and also rehearsed on a copy first. The mapping itself was straightforward — the home-grown stereotypes corresponded cleanly to application component, application service and node — but two categories needed judgement. Elements that were really logical groupings became capabilities or groupings depending on what their relationships suggested they had always meant, and a small set of elements that mixed concerns had to be split by hand. We left the UML content that was genuinely UML — a few class models documenting integration payloads — exactly as it was, because the goal was one language per purpose, not one language everywhere.

Repairing the relationship fabric

The third stream addressed the relationships, and here we deliberately resisted the urge to model everything that was missing. A repository that has just lost its duplicate elements does not need ten thousand speculative connectors added by consultants; it needs the relationships that answer the questions the organisation actually asks. For this client those questions were concrete: which applications support this care process, what does this application depend on, and what breaks if we replace it.

We ran a series of short sessions with application owners, one domain at a time, working directly in the model with a data-entry diagram open. Serving and flow relationships between applications came first, validated against the integration team's interface list rather than against memory. Then realisation links from applications up to the business capabilities the organisation had already defined, which turned the capability map from a poster into a query surface. Where a relationship could not be confirmed, it was not created — a gap someone can see is more honest than a guess nobody questions. The Relationship Matrix earned its keep in these sessions: showing an owner a mostly empty row and asking what belongs in it is a faster and more reliable elicitation technique than any interview script we know.

Reconciling the model against the integration team's interface register produced its own findings, in both directions. A few dozen interfaces in the register had no corresponding flow in the model, which we expected; more interesting were the flows in the model that the register did not know about, some of which turned out to be real, undocumented file transfers that the integration team was glad to learn existed. A cleanup pays for itself in odd moments like that — the repository started returning information the organisation did not have anywhere else, which is the earliest sign that trust is coming back.

We also took the opportunity to make relationship direction mean something. Half the existing serving relationships pointed the wrong way, drawn by whoever needed the arrow to look right on a particular diagram. The convention we set — serving points from the provider to the consumer, flows carry a short label naming what moves — is unremarkable, but applying it consistently is what lets a script answer a dependency question without a person interpreting every connector, and the weekly checks now flag serving relationships whose direction disagrees with the interface register for someone to correct.

Working around live projects

None of this happened in an empty repository. Two transformation programmes were modelling actively throughout the engagement, and asking them to stop for a quarter was never an option. The practical answer was to treat the cleanup as a series of small, announced interventions rather than one long occupation. Each merge wave named the packages it would touch, the architects working in those packages got a week's notice and a list of the elements affected, and the write window itself was short — an evening, usually — with the repository back in normal use the next morning.

Sparx EA's package-level security helped more than we expected. We enabled it with per-package locks for the duration, not to keep people out permanently but to make the boundary between "being cleaned" and "safe to edit" visible inside the tool itself, rather than relying on people reading announcements. An architect who tried to edit a package mid-wave hit a lock with our name on it, which is a far better outcome than a silent collision discovered during verification. Baselines completed the safety net: before each wave we took baselines of every affected package, giving us a documented restore point whose existence made the whole exercise far easier to approve. The one genuine conflict of the engagement — a programme architect who needed an element renamed mid-wave — was resolved in a corridor conversation, which we took as evidence the communication overhead was pitched about right.

The archive branch played a part here too. Because finished-project models had been moved aside at the start, the live programmes were the only other writers in the shared landscape, which kept the coordination problem small enough to manage with a calendar and a spreadsheet rather than a change-control board.

Validation that keeps it clean

A cleanup that ends with a clean repository has a shelf life of about six months. The lasting change came from wiring quality checks into the team's routine, so drift is caught in days rather than discovered in the next crisis. We configured Sparx EA model validation to enforce ArchiMate relationship legality, and complemented it with the checks validation cannot express: the duplicate detector from the assessment, rewritten to run weekly and report new candidate pairs only; a naming convention check; a stereotype whitelist per package branch; and an orphan report that flags elements created more than a month ago that still sit on no diagram and in no relationship.

The output lands as a short quality report generated straight from the model, reviewed for ten minutes in the team's existing weekly meeting. Ownership made the difference here: each top-level package branch now has a named owning architect, set as a tagged value on the package and honoured in review, so every finding in the report has exactly one person whose job it is to resolve it. None of this required additional tooling beyond the scripts and a scheduled task — the kind of automation any team can run, and the kind we help teams set up in our Sparx EA consulting work.

What changed for the architects

The visible result is easy to state: a search for any clinical application now returns one element, carrying the relationships and ownership information a project needs on day one. The duplicate population went from several hundred confirmed pairs to a weekly report that usually finds none, and the untyped-element count in the shared landscape packages went to zero and has stayed there.

The more valuable result is behavioural. Project architects started opening the repository again, first to read and then to contribute, because the cost of finding things had collapsed. The head of architecture began answering programme-board questions with views generated from the model rather than slides assembled the night before — and, tellingly, began refusing to answer questions the model could not support, which did more for modelling discipline than any convention document. Two of the organisation's architects worked alongside us throughout, ran the later merge waves themselves, and now own the scripts outright. We regard that as part of the deliverable: a cleanup the client cannot repeat without us would be a dependency, not an improvement.

The repository got its first real test about a month after the final wave, when the organisation began planning the replacement of its laboratory information system. The question — what connects to it, which care processes depend on it, what has to be rebuilt or re-tested — is exactly the one the old repository would have answered wrongly. This time the impact view came out of the model in an afternoon: the interfaces from the reconciled register, the dependent processes from the workshop sessions, the ownership from the tagged values. The programme used it as the starting inventory for its vendor conversations. Nothing about that view was sophisticated. It was simply true, which is what the whole exercise had been for.

What we would do differently

Two lessons are worth passing on. First, we spent our earliest sessions debating edge cases in the canonical rules that, in the event, almost never occurred, while the genuinely contentious question — which copy survives when both are well-connected — surfaced only once real pairs were on the table. We now start rule workshops from a sample of thirty real candidate pairs rather than from principles, and get to a workable convention in half the time.

Second, we underestimated how much of the repository's bad reputation would outlive its bad content. Weeks after the clinical wave was verified, people were still adding disclaimers when quoting the model. Trust followed usage, not announcements — it returned only as people queried the repository and were not burned. If we ran the engagement again, we would publish the weekly quality report to the whole IT department from the very first week, findings and all, because watching the numbers fall in public is what actually rebuilds belief in a repository, and it cannot start too early.

If your repository has reached the point where people route around it rather than through it, that is recoverable — we have done this often enough to know the pattern. You can reach us through our contact page.

This case study describes a representative engagement pattern. Organisational details are illustrative and do not identify a specific client.