Opening Architecture to a Wider Audience

Three architects, thousands of readers

The organisation, a university with several faculties and a central IT division, had an architecture function of exactly three people. Between them they maintained a serious Sparx EA repository: the application landscape, the integration flows, the data domains, and the architecture of every major programme the institution had run for years. The model was good. Its audience was three.

Everyone else encountered the architecture second-hand. Deans and faculty boards saw it as slides prepared for a specific meeting. IT service managers saw it as diagrams pasted into the service catalogue, of uncertain age. Project boards saw whatever the project architect had time to export. The architecture team estimated they spent a day or more each week producing tailored extracts of a model that already contained the answers — a translation tax paid over and over, with each translation going stale the moment it left the tool. The head of IT put the brief simply: the university had paid for this knowledge once and was paying again every time someone needed to see it. Make the repository readable by the people who need to read it, without turning any of them into modellers.

Why the PDFs kept failing

The team had tried document exports before we arrived, and the attempt is worth examining because its failure was structural rather than a matter of effort. Generated documents answer the question their template anticipated; stakeholders arrive with the question next to that one. A service manager reading an application factsheet wants to follow one integration to the system on its far end — a document dead-ends there, and the follow-up lands back on an architect's desk, which is precisely the tax the exports were meant to abolish.

Worse, documents detach from time. Within a month nobody knows whether the PDF on the intranet still describes reality, and a reader burned once by a stale export discounts every export after it. The team's conclusion, which we endorsed, was that publication had to be navigable and had to be visibly live — two properties no static document set provides. What documents remain good for is the fixed snapshot: the architecture annex of a project charter, the state of the estate at a governance gate. The university kept document generation for exactly those moments and stopped pretending it was a publication channel.

What the first weeks told us

Before recommending anything we spent time on the receiving end of the problem, interviewing a dozen of the people the architecture was failing to reach: two deans, a handful of service managers, the chairs of two project boards, and the quality office. We asked each the same things — when you last needed to know something about a system or a project's architecture, where did you look, how long did it take, and what did you do with the answer. The pattern was uniform and a little humbling for everyone involved. Nobody had looked anywhere first; every trail began with an email to a person, usually the same two people, and the answer arrived as an attachment that then began its own second life, forwarded and re-quoted long after it stopped being true.

Two findings from those interviews shaped the design directly. First, no interviewee wanted the model — they wanted answers with dates on them, and several said explicitly that knowing when a diagram was last confirmed mattered more than any additional detail. That sentence bought the review-date convention its place at the centre of the publication design. Second, the audiences barely overlapped in what they needed: the service managers' questions and the deans' questions shared vocabulary but not altitude. One portal per institution, one entry per audience became the brief in its final form, and the interview notes settled several later arguments about what belonged on each landing view — we could simply quote the audience.

Standing up Pro Cloud Server and WebEA

The technical spine of the answer was Sparx's own: Pro Cloud Server in front of the repository, and WebEA as the browser interface for everyone without a modelling licence. The repository itself moved from a file share onto the university's SQL Server estate as part of the work — a move overdue for reasons beyond publication — with Pro Cloud Server connecting to it and the architects' desktop clients reconnecting through the cloud connection rather than direct to the database. That reconnection matters operationally: it ends the era of database credentials on modelling workstations, and it gave the university one controlled doorway to the model with logging on the door.

The installation itself is not the story — a Windows server, TLS certificates from the university's own authority, the firewall opened to the campus network only, and the IIS integration configured for the university's single sign-on so WebEA visitors authenticate with their normal institutional accounts. We sized it conservatively and it has never been the bottleneck; a modelling repository's read traffic is light by web standards even when the whole institution can reach it. The real work, and the majority of the engagement, was everything around the installation: deciding what those readers would see when they arrived. A portal that opens onto a modeller's package tree has technically published the model and practically published a maze.

A repository reorganised for readers

A repository organised for maintenance is organised by how architects think: by domain, by notation, by programme, with working areas and half-finished branches sitting beside the curated content. None of that should meet a reader. We restructured the top of the package tree into two worlds: a published world, curated and stable, and a working world hidden from the browser audience using Pro Cloud Server's visibility levels — the row-level mechanism that needs exactly the SQL Server hosting the repository had just moved to, and one of the quiet reasons that database family was chosen. Promotion from working to published became a deliberate act — a small ceremony the three architects perform when content reaches the standard the published world promises — rather than an accident of where an element happened to be created. Between ceremonies the published packages stay locked under EA's user security, so a mid-week correction is made in the working world and reaches readers only through the next promotion — WebEA shows the model live, and the lock is what keeps the live view from ever meaning half-edited.

The published world is organised by the questions readers actually bring: what applications exist and who owns them; how the systems supporting a given service connect; what the architecture of each active programme looks like; what standards and decisions apply. That organisation cut across the team's working structure, and Sparx EA absorbed the mismatch well — an element lives once — after promotion it sits in the published domain packages — and the audience-facing organisation is built over those packages with curated diagrams and package views, so nothing is duplicated in order to be published; the working world holds only drafts on their way in. The published packages carry a short plain-language description at every level, because a package name that is obvious to an architect is a riddle to a dean.

Landing pages instead of a tree

WebEA opens onto whatever the configuration points it at, and we pointed it at a purpose-built landing diagram rather than the package browser. The landing diagram is a simple navigation view — a handful of large, labelled tiles, each hyperlinked to the entry diagram for one audience's world — built with ordinary Sparx EA elements and diagram hyperlinks, no extensions required. One tile per audience: the application catalogue for service managers, programme architecture for project boards, the capability and service view for faculty and executive readers, standards and decisions for everyone who is sent there by a governance process.

Each audience's entry diagram continues the same pattern one level down, so a reader is always two or three clicks from what they came for, and every diagram carries a one-line purpose statement in its notes — what this view shows, what it deliberately omits, and the date it was last reviewed. The purpose statements began as our discipline and became the team's habit; they are the difference between a diagram that informs and a diagram that gets forwarded with the question "is this still right?".

Diagrams redrawn for a lay audience

Publishing the architects' working diagrams unchanged would have failed politely. A working diagram is dense because density serves its maintainer; a reader needs the opposite. For each published view we applied a short set of rules that have nothing to do with notation and everything to do with respect for the reader: one question per diagram; no more than a couple of dozen elements; relationship labels in words rather than left to notation alone; a legend on every view that uses colour to mean something; and plain-language element notes, because WebEA shows an element's notes and properties to anyone who clicks, which turns every published element into a small factsheet whether or not anyone planned it that way.

The redrawing was the engagement's least glamorous stream and its highest-leverage one. It also forced useful honesty: several working diagrams turned out to be unpublishable not because they were cluttered but because they were quietly out of date, and the act of preparing them for readers became the audit that fixed them. A publication programme is, among other things, a quality programme wearing better clothes — the same effect we see when teams prepare a repository for any external scrutiny, and one of the reasons we encourage clients in our Sparx EA consulting work to publish early rather than after the model is "ready".

Access without anxiety: the security model

Opening a repository to an institution raises a reasonable fear: what if someone sees what they should not, or worse, changes it? The answer was layered and mostly boring. WebEA visitors authenticate through the university's single sign-on, so there are no shared portal passwords to leak. Their access is read-only by policy — the university chose not to enable WebEA's commenting and editing features in the first year, preferring adoption before interaction. And the visibility levels expose only the published world; the working world, with its drafts and its half-thoughts, does not exist as far as the browser is concerned.

Within the published world we resisted fine-grained restrictions almost entirely. A university is not a bank; the architecture of the student information estate is sensitive in places, but the default answer to "who may see the application landscape" in this institution was "anyone with an institutional account", and complicating the model's security story to protect the mundane would have cost more in administration than it bought in safety. The one exception — a package of security-relevant infrastructure detail — stayed in the working world, published instead as a deliberately generalised view. Deciding that in one meeting, and writing it down, spared the team a year of case-by-case anxiety.

Teaching people to read, not model

Adoption did not happen because a URL was announced. It happened because the team ran, with our help, a short campaign of audience-specific introductions — forty-five minutes each, in the audience's own meeting slots rather than in training rooms. The sessions taught nobody ArchiMate. They walked each group from their landing tile to two or three answers they genuinely needed that week: here is the system you asked about last month, here is what it connects to, here is the date this view was last reviewed, here is the element note that names its owner. Reading, not modelling, and reading their own questions specifically.

Two structural choices supported the habit afterwards. Every architecture slide the team produces now carries the WebEA link to the live view it was exported from, so meetings keep flowing readers back to the source. And the architects adopted a strict reply pattern for questions the portal can answer: the answer, plus the link, plus nothing else — polite, useful, and quietly retraining the institution about where answers live. Within a term, the links began appearing in other people's documents, which is the adoption signal that matters: the portal had become how the university cites its own architecture.

What WebEA will not do

An honest account includes the edges, and WebEA has them. It is not a portal product you can restyle: the university's brand appears in a logo and a colour accent, and no further — an institution wanting a fully branded architecture site with its own navigation and search would need a different publication approach layered on top of the repository. Very large diagrams render but do not delight on the web, which we turned into a virtue by treating "too big for WebEA" as a review comment on the diagram rather than a deficiency of the tool. Deep model search in the browser is serviceable rather than wonderful, which is why the landing-page navigation carries as much weight as it does. And WebEA's liveness cuts both ways: it shows the model as it is, so the publication boundary and the promotion discipline are not optional refinements — they are what stands between the institution and a portal full of drafts.

None of these limits argued against the choice. For a three-person team already invested in Sparx EA, wanting live, navigable, access-controlled reading for a campus audience, Pro Cloud Server and WebEA were the shortest defensible path — and when a certificate renewal later broke the desktop clients' cloud connection for a morning, it proved to be well-trodden territory rather than an exotic failure. But we would give a different answer to a different starting position, and we said so in the recommendation that opened the engagement.

Keeping the portal alive

A publication channel is an operational commitment, and we set the university up to carry it with the resources it actually has, which is to say almost none beyond the three architects and a shared infrastructure team. The running arrangements are deliberately light. Pro Cloud Server updates ride the university's normal patching calendar, tested against a copy first because the desktop clients and the server prefer to move together. The repository database joined the institution's standard backup regime the day it left the file share, with a restore actually rehearsed once — a step we insist on, since a backup that has never been restored is a rumour. The promotion ceremony from working world to published world happens on Friday mornings, takes half an hour, and doubles as the team's review of what changed that week.

The overdue-view script closes the loop: it lists every published diagram whose review date has aged past its audience's tolerance — quarterly for programme views, twice a year for the landscape — and its output opens the Friday session. Most weeks the list is empty or nearly so, precisely because it is looked at weekly. None of this needed new tooling or a bigger team; it needed the operational habits to be designed at the same time as the platform, rather than discovered afterwards in the form of a stale portal and an awkward meeting.

What changed in six months

The translation tax fell first. The team's export-on-request work shrank from a day or more a week to the occasional genuine snapshot, and the time went back into the model — visibly, because the published world's review dates kept advancing. The quality of incoming questions changed next: stakeholders began arriving with element names and view links rather than descriptions, which shortens every conversation that follows. Programme boards started opening the live programme view in meetings rather than commissioning a deck, and at least one procurement exercise sent vendors WebEA extracts as the statement of the current estate, with the architecture team's blessing and considerably less of their labour.

The subtler change was to the architecture function's standing. A model three people could see was, institutionally, those three people's opinion. A model the whole campus reads, with review dates on every view, is infrastructure. The distinction surfaced in small ways — the architecture team being asked to publish a view rather than attend a meeting — and in one large one: when the next strategic programme was chartered, the charter cited the portal's views as its baseline description of the estate, which had never happened with a deck.

What we would do differently

We would start the diagram-redrawing stream on day one rather than after the platform work. The server was ready weeks before enough published views existed to justify an announcement, and the delay drained the momentum the announcement needed; the launch landed later and softer than it should have. The platform is the quick part of a publication programme, and scheduling it first flatters the project plan while deferring the work that actually determines the outcome — a sequencing mistake we have not repeated.

We would also set the review-date discipline with more teeth from the beginning. A view's last-reviewed date is a promise, and promises need owners and reminders; we added the model script that flags overdue views only in the final month, after a stakeholder politely pointed at a view whose date had quietly aged past its meaning. The script is twenty lines and should have existed in week one. Liveness, it turns out, is not a property of the technology — WebEA was faithfully showing a diagram nobody had looked after. It is a property of the practice, and the practice needs the same automation as everything else worth keeping.

If your architecture is excellent and invisible — maintained by a few, read by almost no one — publication is the highest-leverage work available to your team, and it is more organisational than technical. We have helped teams of two or three open their repositories to whole institutions. 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.