Why Ilograph Added Contexts

Adding contexts to an Ilograph diagram

In this article, we’ll look at the importance of contexts in system architecture diagrams and recent enhancements to how they are handled in Ilograph.

Defining diagram “contexts”

System architecture diagrams visually document complex technical systems. Most come in the form of either relational or sequence diagrams, with boxes representing system resources, and arrows representing relations (or steps) between them.

Like in the example below, the boxes (or nodes) with lines going between them are typically the main focus. We’ll refer to these as subject nodes. The background nodes (circled) are what we will refer to as context nodes. Context nodes implicitly give us information about where a subject node lives, its membership, or some other parent-child relationship:

A system diagram with context resources
Context nodes (circled) give the viewer critical background information about a system.

Critically, the same basic diagram can be drawn with different contexts, or no context at all. In the following diagram, the foreground resources and the arrows between them are the same, while the context nodes change (or, in one case, are removed):

The same diagram can be drawn with different (or no) context nodes.
The benefits of contexts

All else being equal, more information is better when diagramming. Whether they represent concrete or abstract resources, context nodes provide important background information that gives broader understanding of a system. This information is especially useful to newcomers/new hires, especially because experts may inadvertently omit it during discussions.

Furthermore, if using an interactive diagramming tool like Ilograph, the level of detail can be lowered to shift focus to the context nodes themselves. This provides a higher-level view of the system and the relations between its parts:

Reducing detail reveals relations between context nodes.

Going the other way, contexts also provide bounded scopes to “zoom in” on:

Contexts allow for zooming into diagrams.

The old method of using contexts in Ilograph

Default context and overrides

Since its inception, Ilograph has supported contexts. Resources in Ilograph are defined as a tree structure of parent and child nodes. This resource tree is a shared model used in different diagrams (called perspectives in Ilograph). By default, these perspectives are drawn with contexts derived from this tree:

A system diagram with default context resources
Unless otherwise specified, contexts in Ilograph are derived from the resource tree.

Diagram authors can change the context on a per-perspective basis using overrides. In a perspective, the parent overrides are declared individually (in the overrides section):

A system diagram with overridden context resources
Using overrides, these nodes are drawn with a different context.

In the above two images, notice that the subject nodes and the arrows between them are identical; only the contexts nodes have changed.

Mixing in overrides with extends

Context overrides apply only to the perspective they are defined in. To avoid repeating the same overrides in multiple perspectives, diagram authors can define overrides in hidden perspective(s) and then extend them in other perspectives:

A system diagram with mixed-in context resources
Contexts can be mixed-in to perspectives using the *extends* keyword.

Using this method, authors can mix-and-match many such “context” perspectives with “content” perspectives (which contained the actual relations/steps between nodes). Each combination results in a new perspective which appears in the tray at the bottom of the app, like in this example.

Drawbacks of the old method

While this technically works, there are many drawbacks to this method:

Parent overrides are not defined as a tree

While resources are defined as a parent-child tree, parent overrides are defined as a list of modifications. Not only is this syntax incongruous with how resources are defined, the overrides list is difficult to organize and understand.

Mixing perspectives isn’t intuitive

The primary purpose of perspectives in Ilograph is to show different relations (or sequences) between a common set of resources. The method of mixing “content” and “context” perspectives (described above) certainly works, but it isn’t intuitive and requires the use of the relatively advanced extends keyword. Furthermore, the diagram source code is cluttered up with many hidden perspectives.

It produces too many perspectives

Mixing every “content” perspective with every “context” perspective can result in a large number of perspectives appearing in the tray:

An Ilograph perspective tray with many perspectives
Mixing in contexts can explode the number of perspectives in a diagram.

With too many combinations, users have to scroll to see them all. Furthermore, knowing which perspectives contain which combinations of content and context isn’t always clear.

Context is fixed during walkthroughs

Walkthroughs are defined on a per-perspective basis. Because perspectives can have only one context, this means walkthroughs can show nodes using only one context. Explaining different contexts using walkthroughs is therefore not possible.

The new contexts keyword in Ilograph

Because of the above drawbacks, Ilograph has a new top-level contexts keyword. This optional keyword allows diagram authors to define contexts that are shared across all perspectives. These contexts are defined as a tree of parent-child nodes:

An Ilograph diagram demonstrating the new 'contexts' keyword
Defining contexts using the new *contexts* keyword.

Diagram viewers can then independently select each context and perspective:

Contexts can now be selected independently of perspectives.

The result is a more intuitive UI. There are far fewer perspectives in the perspective tray, and users can now expect each one to have unique relations or sequences.

The diagram source code is also clearer and less cluttered. Using the contexts keyword better signals the intent of the diagram author compared to defining contexts in hidden perspectives. And defining contexts as a tree is more in step with how resources themselves are defined.

Lastly, a perspective’s context can now be changed during walkthroughs. Along with explaining relations or sequences, walkthroughs can now also explain the different contexts nodes appear in.

Click here to view an example Ilograph diagram that uses contexts.

Is the old method going away?

No. Both perspective overrides and extending perspectives are here to stay, so the old method of mixing-and-matching perspectives will continue to work. Diagram authors are encouraged, however, to switch to the new contexts keyword to provide viewers (and themselves) with the best experience.

Questions or comments? Please reach out to me on LinkedIn or by email at

Share this article on LinkedIn

Share this article on Facebook

Share this article on Twitter