Context and Abstractions

To be able to describe our architecture to all our stakeholders it's important to not try and describe too much at once.

We need to split it up into different areas (context) and we need to describe it in different levels of technical detail (abstractions).

Dividing your architecture into contexts

It's tempting to start and describe your full architecture in your first diagram. That might work if you have a smaller architecture. But once you have a big bigger, more complex architecture that usually creates diagrams that are hard to grasp for everyone.

You probably already today split up responsibility for your architecture. It could be as simple as some components being owned by one group and another set by another. It could be that all human relations-related components are owned by someone while all finance-related ones are owned by someone else.

How things are divided is different from organization to organization. But try to bring that into how you divide up your diagrams in different contexts in Revision. Dividing diagrams into these smaller areas and not describing everything in one will make them much easier to read and much more useful.

Describing different levels of abstraction

Different stakeholders in your organization will have different interests in detail and scope.

A technical programmer will often be trying to understand how things are connected and working on a low technical level. An owner of a system or a more high-level architect, on the other hand, is more interested in how things different components are connected and how what kind of data flows between them.
We must create diagrams that cater to both of these groups of stakeholders.

Inspired by the C4 model we recommend that you describe your architecture in three levels.

Level 1 - The full context

Level 1 describes a full context. All the concrete components and the data that flows between them.

Focus on just the concrete components and data flow and try not to get into technical details.

Level 2 - High-level container

Describes on a higher level how a component or dataflow is implemented. At this level, we might also include services or dataflow components that are used. If describing a service or a system we might have the modules, connected services and databases included here.

Include some technical details that you think are useful for the consumers of this diagram.

Level 3 - Low-level component

Here we describe the nitty-gritty details of how a component-specific service or component work. All concrete details, rules and technical details might be included here.