Five views and twenty-six decisions

Roar Elias Georgsen, 27 August 2026

Part 7 of 13 in Federating a systems model, written for release v0.3.0.

The story so far

The demo is a SysML v2 model of a five-server query pipeline, published as one federated GraphQL graph by three services in one container. A capacity analysis and a requirements document are joined to the model. Part 6 turned the use cases into requirements. This part is the third gate, the architecture that answered those requirements. It’s drawn as five views for five kinds of reader, with twenty-six decisions behind it.

An architecture description is for people who want different things from the same system. I borrowed the vocabulary of ISO/IEC/IEEE 42010 for it: stakeholders, their concerns, and views that answer those concerns. I followed the standard’s concepts without claiming to conform to it, and nobody has audited the description against it.

Key term View and viewpoint

In ISO/IEC/IEEE 42010, a view is one picture of a system drawn for a particular set of concerns, such as what runs where or how a request flows. A viewpoint is the recipe for that picture: which concerns it answers, for whom, and in what notation. Five views of one system can drift apart, so a good description also says how they correspond.

The description names five readers, each with a question:

• The visitor: does it launch, and does it show something I wouldn’t have believed?
• The model owner: does the model stay the source, and does an edit anywhere land in it?
• The document owner: can I shape the document without touching the model?
• A maintainer: can I read it in an afternoon, build it with Go alone, and change one service at a time?
• An organisation deciding whether it fits: what do the services agree on, and what would we replace?

The last question is the reason the series exists. At the third gate, the reading found that the description had promised that reader an answer and never given one. The answer the description gained is the adoption contract in The architecture in one sitting.

You’ll find the text of each view, with the field ownership table and the process tree, on the architecture page. That page and the decision records together are the record of the architecture. Here’s what each view is for.

The five views

Context: what’s inside and what isn’t

The context view draws the demo as one box, and the browser, the Docker host and the container registry outside it. All the boards are in the architecture views PDF.

Everything the demo needs runs inside one container. Outside it are a browser, the Docker host, and the registry the image is pulled from once, and nothing else. I built the demo to make no connection beyond that boundary while it runs.

Update Changed in v0.4.0

The demo’s own systems model, which part 13 introduces, now puts a second host in the context. A Proxmox VE host can pull the same image from the registry and run the demo on demand (the demo on my own Proxmox host). The board above and the architecture page still show the Docker host alone.

Composition: who answers for which field

The composition view shows which service answers for every field, and the merged graph in which one requirement carries fields from all three.

This is the view the deciding organisation reads. Each of the three subgraphs answers for its own fields, and the fields never overlap. The subgraphs meet on one entity key, the SysML short name. Through @requires, the capacity service asks the router for the parts and connections it needs. The document service answers for an id it has never heard of by saying the requirement isn’t in the document.

Runtime: one edit, end to end

The runtime view follows one edit through the router, the adapter and the capacity service to both web apps, and The architecture in one sitting walks through its seven steps. Beyond those steps, the view shows an asymmetry. An edit to the document goes to the document service alone. It changes the document’s version and leaves the model’s version untouched, and that’s the whole of what the document owner was promised.

Deployment: one container, one process tree

The deployment view shows one container with one process tree, the build stages, and the workflow that publishes on a version tag.

One Go binary supervises three services and the vendor’s router inside one container, and only one port is published. The image is built for two processor architectures and published when I push a version tag.

The adapter: text in, projection out

The adapter view is a pipeline of four packages, with the patch path from an edit back to the syntax tree.

The adapter parses the model text into a tree in which every node remembers where it came from in the source. An edit replaces one number at its position, and the adapter parses the text again. So the served text and the projection can never disagree, and the adapter never holds a second copy of the model.

Twenty-six decisions

The main choices behind those views each have a decision record, with its context, the alternatives that lost, and the consequences. Twenty-four of the records came from decisions already taken in the brief, the plan and the engineering log. Two more turned up when the traceability showed requirements with no decision behind them. The decision index lists thirty-one by release v0.3.0, because five more came during the build and after it.

Update Changed in v0.4.0

The index lists thirty-four records now. Since v0.3.0 it has gained three, a language model experiment kept outside the product, the demo on my own Proxmox host, declared in OpenTofu and acceptance criteria as Gherkin scenarios.

The twenty-six fall into five groups:

• The shape of the system: federation over a single service, Cosmo as the platform, one binary, one port, the router as a child process, composition committed and tested for drift and telemetry off.
• The analysis: an idealised capacity model, the rollup as a maximum flow, the quantity read from the constraint, connection direction and reasons from templates.
• The adapter: files instead of a repository, editing as scaffolding, a curated projection, a hand-written subset parser, short names as keys and SysML 2.0 as the target.
• The two apps: events that carry a version number, plain web apps with no build step, the document owning its structure and the model’s text beside its wiring in the viewer.
• The repository: generated code exempt from the empty-interface rule, publishing on tags, the Markdown record and the A3 overview, tracked test helpers and a light requirements scheme.

The reading at the third gate overturned none of them. Its fixes were to mechanisms and to gaps in the description. That told me the decisions had settled before the description was drawn.

For a reader with only a quarter of an hour, I cut all of this down to single sheets of paper, which is where An A3 sheet for a fifteen-minute reader picks up.

Previous: From use cases to requirements · Index: Federating a systems model · Next: An A3 sheet for a fifteen-minute reader