Governing an Architecture Practice With a Repository

The tool changes the practice

Teams adopt a repository expecting a storage change and get a process change. Once there is a single place where architecture lives, with history and permissions, questions that were previously informal acquire answers — and therefore owners.

Who may approve a baseline. Who may grant access. What happens when two teams disagree about a shared element. These were previously resolved by conversation. Now they are configuration, and configuration needs a decision.

Four roles that emerge

These are not job titles. Several may be the same person in a small practice. What matters is that the responsibilities are distinguished, because the permissions are.

Architect

Models, publishes, creates content. Deliberately cannot administer: cannot grant themselves access to another project, cannot force-release someone else's lock, cannot delete a baseline. Not because they are not trusted, but because separating these makes the audit trail meaningful.

Repository administrator

Grants, groups, lock administration, baselines, backups. Frequently someone who does not model day to day, which is healthy — it prevents administrative convenience from being decided by the person it is convenient for.

Architecture manager

Reads, reviews, reports. Uses the portal rather than the modelling tool. This role is the reason a browser interface exists at all, and it is usually under-served because tooling is designed by and for modellers.

Auditor

Reads audit events and history. Nothing else. Worth defining explicitly even if the role is used twice a year, because the alternative when the question arrives is granting someone administrator rights temporarily and forgetting to remove them.

The workflow that follows

A practice with a repository tends to converge on the same rhythm, and it is worth adopting deliberately rather than discovering:

1. Architects work in their own projects, publishing revisions freely. Revisions are cheap and history is the point.
2. Shared elements live in a common project with tighter permissions, because a change there affects everyone.
3. At a governance point — a board, a release — a baseline is created and named after the decision it records.
4. The published portal, if there is one, is generated from that baseline rather than from current state.
5. Access is reviewed on a cadence, using the effective-permission view.

The shared-element problem

The genuinely hard governance question a repository surfaces: who owns an element two teams depend on?

Left unaddressed, one of two failures happens. Either everyone can edit it, and it changes under teams that depended on it. Or nobody can, and it goes stale because the person who could is not the person who noticed.

What to decide before rollout

Four questions, and having answers ready avoids the first month being spent on them:

• Who creates projects, and on what basis?
• Who may create and name a baseline?
• What is the process when a lock must be force-released?
• How often is access reviewed, and by whom?

None is difficult. All are considerably easier to answer in a meeting beforehand than in a ticket queue afterwards.

The meeting that changes

One concrete effect worth anticipating: the architecture board meeting gets shorter and better, or it gets worse, depending on one decision.

If the board reviews a baseline — a named revision, published in advance, with a comparison against the previous one — the meeting is about decisions. If it reviews whatever is currently in the repository, the first twenty minutes are spent establishing what people are looking at.

Publishing a comparison against the last approved baseline before each board is a small piece of automation that changes the character of the meeting more than any governance framework.

Handling disagreement

A repository makes disagreements visible that were previously diffuse, and it needs an answer for them.

Two teams model the same real-world thing differently. One publishes; the other objects. Previously this stayed unresolved in two separate files. Now there is one element, one owner, and a conflict that has to be settled.

What governance stops being once it has a repository

Most architecture governance is enforced socially: a review board, a checklist, a person who notices. That works at the scale where one person can hold the estate in their head and stops working at exactly the point nobody notices it has stopped.

A repository does not make governance automatic. It changes which parts have to be done by people. Three things move from judgement to query:

• Conformance to the metamodel. Whether an element has an owner, a lifecycle, a criticality rating. Previously spotted in review, now a report anyone can run before the review.
• Coverage. Which parts of the estate have been touched this year and which have not. Nobody can assess this by reading diagrams.
• Traceability. Whether a requirement connects to something that implements it. A graph question, and graphs are what the repository stores.

What stays human is everything about whether the architecture is good. No query tells you that a service boundary is in the wrong place.

The reports worth running

A repository will happily generate fifty reports nobody reads. Four earn their place, and they earn it by changing what somebody does.

Each of these is a single query against the record store. None of them is answerable from a set of diagram files.

Governance that runs on a cadence, not on requests

The failure pattern is governance that only activates when someone submits something. Everything not submitted is unexamined, which is most of the estate, and the parts nobody submits are exactly the parts that have drifted.

A cadence fixes this cheaply. Monthly: the four reports above, and the exceptions list. Quarterly: a scoped review of one domain, rotating, so every domain is looked at once a year whether or not it asked to be. Annually: the metamodel itself, because the conventions that made sense two years ago accumulate special cases.

None of this needs a meeting. Three of the four monthly reports should be a message to one person with a list in it.

The metrics that mislead

Repositories make it easy to count things, and counting the wrong things actively harms a practice. Two are worth naming because both sound reasonable.

Number of elements modelled. This rewards volume. A team measured on it will model every server, and the estate becomes an inventory nobody can navigate. The useful version is the proportion of business-critical applications that are modelled to the agreed depth — a number that can go down when the business adds systems, which is the point.

Number of diagrams. Rewards duplication. Four views of the same six applications is four diagrams and one insight. Counting distinct questions the portal can answer is harder to measure and closer to what matters.

Exceptions are the governance record that matters

Every architecture practice grants exceptions. A team ships something that does not conform because the deadline is real and the standard is not worth missing it for. That is a legitimate decision and pretending otherwise just moves it off the record.

What separates a functioning practice from a decorative one is whether exceptions have four properties:

• Recorded against the element, not in a document. An exception nobody encounters when they open the model does not exist.
• Owned by a named person, not a team. Teams do not chase their own exceptions.
• Given an expiry date. An exception without one is a silent standards change.
• Counted. Thirty open exceptions in one domain is not thirty problems, it is one: the standard is wrong.

That last point is the one worth internalising. A rising exception count is usually evidence about the standard rather than about the teams, and a practice that reads it the other way spends years enforcing something that does not fit.

Governing the metamodel itself

The metamodel — which element types are allowed, which relationships are permitted, which properties are mandatory — is the one artefact that governs everything else, and it is usually the least governed thing in the estate.

It drifts in a predictable way. Someone needs a concept the metamodel does not have, adds a stereotype, and does not tell anyone. Two years later there are four stereotypes meaning roughly the same thing, and any query that filters by type is quietly wrong.

Three controls, none of them heavy:

1. A short list of who may add an element type. Two or three people, named, and everyone else raises a request.
2. An annual review that lists every type in use with a count. Types with a count of one or two are either mistakes or evidence that a modeller needed something the metamodel lacks. Both are worth ten minutes.
3. A rule that new mandatory properties apply going forward only, unless someone commits to backfilling. Retroactive mandatory fields produce a thousand-row conformance report nobody will ever clear, and the report becomes noise that hides real findings.

What to do when the repository disagrees with reality

It will. Someone decommissions a system and the model still shows it. A team stands up an integration nobody modelled. The gap between the repository and the estate is the practice's real quality metric, and almost nobody measures it.

Measuring it needs an external reference — a CMDB, a cloud inventory, a licence register, an API gateway's route table. Any of them, compared against the model, produces three lists: in both, in the model only, in reality only.

The third list is the valuable one and the uncomfortable one. It is the shadow estate: things running that the architecture does not know about. Running that comparison once, even badly, tells a practice more about its own accuracy than a year of review boards.

The honest version of this is that the comparison never reaches zero, and a practice that treats a non-zero result as failure will stop running it. The number to watch is the direction of travel.

What to do in the first ninety days

A repository arrives and the temptation is to design the whole governance model before anyone uses it. That produces a document. The order that works starts narrow and lets the estate tell you what it needs.

1. Weeks one to three — decide what an element must have. Owner, lifecycle, criticality. Three properties, no more. Do not backfill; apply it to anything touched from now on.
2. Weeks four to six — run the no-owner report and act on it once. Not to clear it, which is not achievable, but to find out how bad it is and whether anyone will act when told.
3. Weeks seven to ten — scope permissions properly. This is the tedious one and it does not get easier later, because every week adds users to the over-broad default.
4. Weeks eleven to thirteen — publish something. Any scope, one audience. A repository nobody outside the architecture team can read will not survive its first budget review, and the fastest way to make it defensible is to have someone else depend on it.

Everything else — exception workflow, metamodel review, conformance assessment — waits until there is enough content for it to be about something.

The whole thing in an hour a week

Governance descriptions have a way of implying a bureaucracy, so it is worth closing with the honest time budget, because for a mid-sized practice the entire operating rhythm described above fits inside one recurring hour — provided the repository is doing the clerical work.

Fifteen minutes on the reports: the coverage list of elements in no perspective, the quality trend from the gate, the exceptions approaching their expiry dates, all generated, all read rather than compiled. Fifteen on the week's revisions — the semantic change list, skimmed for anything that touches a shared element or a regulated perimeter, with one or two flagged for a closer look. Fifteen on the standing queue: the access request that needs a decision, the waiver renewal, the metamodel change someone proposed. And fifteen of actual conversation — the one disagreement worth having live rather than in comments. Everything else the sections above describe happens asynchronously, inside the workflow, attributed and recorded, without a meeting attached.

The comparison worth making is with the practice next door that governs by document and committee: a monthly board with pre-reads nobody finished, decisions minuted into a file nobody reopens, and every question between meetings answered by whoever replies first. Same intent, ten times the ceremony, a fraction of the traceability. The repository does not reduce governance; it compresses the overhead until what remains is the judgement — which was the only part that ever needed humans in a room, and the only part an hour a week cannot delegate.

Governance with a repository underneath it is not stricter than governance by committee — it is lighter, faster and harder to fake, which is a different thing entirely. The rules run as checks, the decisions leave records, the exceptions carry expiry dates, and the humans spend their hour on judgement. Practices that make this transition stop experiencing governance as overhead within a year; it becomes simply how the work moves — visible, attributed and boring, which is governance succeeding.