Composable Work Systems Topologies with PlantUML

Author

Thomas Krause

Published at

February 8, 2025 1:46 PM (GMT+1)

Tags

flightlevelsvisualizations

Summary

I explore composable work systems using PlantUML techniques.

After starting with using PlantUML for visualizing Work Systems Topologies a while ago, it has become a day-to-day tool for me. And it works nicely as long as the work systems covered have a small size. To keep them manageable, especially over time I was thinking about means to move from “one big document” to smaller decentralized documents that are composable to the full Systems Architecture level.

Luckily PlantUML has basic means to achieve this. Similarly to reusing styles with !include, we can also include existing work system definitions and combine them to specific views. Let’s start.

General Approach

Let’s say we have an existing product 1.

@startuml Product 1

title Work System - Product 1

package FL3 <<FL3>> {
  [Strategy] <<FL3>>
}

package FL2 <<FL2>> {
  [Product 1] <<FL2>> <<WS1>>
}

package FL1 <<FL1>> {
  [Team A] <<FL1>> <<WS1>>
  [Team B] <<FL1>> <<WS1>>
}

[Product 1] -up-> [Strategy]
[Team A] -up-> [Product 1]
[Team B] -up-> [Product 1]

@enduml

This results in the following diagram (I did not add styles yet, we will do this later).

The company has a second product and the respective work system.

@startuml Product 2

title Work System - Product 2

package FL3 <<FL3>> {
    [Strategy] <<FL3>>
}

package FL2 <<FL2>> {
    [Product 2] <<FL2>> <<WS2>>
}

package FL1 <<FL1>> {
    [Team C] <<FL1>> <<WS2>>
    [Team B] <<FL1>> <<WS2>>
}

[Product 2] -up-> [Strategy]

[Team B] -up-> [Product 2]
[Team C] -up-> [Product 2]

@enduml

Now we want to combine the two work systems into a full view of the company’s system architecture.

@startuml Product 1 and Product 2 merged

' We add the styles here
!define fllib https://raw.githubusercontent.com/worksystems-design/plantuml-flightlevels-lib/refs/heads/main/defs
!include fllib/fl-wst.iuml
!include fllib/fl-wst.iuml!wsd.branding

' We include the two work systems
!include ws1.puml
!include ws2.puml

title Product 1 and Product 2 merged

@enduml

Nice, both products are nicely placed at FL2, connected to strategy. The teams are placed together on FL1, team B is contributing to both products.

So what?

So far this seems like a technical playground only, it’s not. It opens up a couple of interesting usage scenarios:

1. In a bigger system, you can keep the authority at work systems level where it belongs - to the people contributing to the local system. However, a systems architecture view is still possible, it is built with the details coming from the contributing work systems. Essentially this follows the principle of subsidiarity, applied to work systems topologies.
2. We now have the foundations to play with What-if scenarios. We would take the existing pieces of a systems architecture and combine it with options to add or change a single work system.
3. Work systems might evolve, change, dissolve etc. with different pace over time. If we start to track the local changes, we would have a complete history over time. This is something I will explore more in the near future. Working title: Work Systems Ecocycles.

Let’s see how far we can come supporting these scenarios with PlantUML. In the What-if scenario we might like to see the contributors and connections added to an existing systems architecture.

@startuml merged

!define fllib https://raw.githubusercontent.com/worksystems-design/plantuml-flightlevels-lib/refs/heads/main/defs
!include fllib/fl-wst.iuml
!include fllib/fl-wst.iuml!wsd.branding

' The existing Systems Architecture
!include ws1.puml

' Here we're adding styles to show the delta
<style>
    componentDiagram {
      arrow {
        LineColor LimeGreen
        LineThickness 4
      }
      .WS2 {
        FontColor LimeGreen
        FontStyle Bold
      }
    }
</style>

' Canges to be introduced
!include ws2.puml

title Product 1 and Product 2 merged, with Delta

@enduml

One more thing we might like to be able to do is to only focus on Flight Levels 2 and 3. Easy to do with PlantUML, we add a single line hide <<FL1>> to the top level diagram. This gives a different view, based on the very same source documents.

@startuml merged

!define fllib https://raw.githubusercontent.com/worksystems-design/plantuml-flightlevels-lib/refs/heads/main/defs
!include fllib/fl-wst.iuml
!include fllib/fl-wst.iuml!wsd.branding

!include ws1.puml

' Here we're adding styles to show a delta
<style>
    componentDiagram {
      arrow {
        LineColor LimeGreen
        LineThickness 4
      }
      .WS2 {
        FontColor LimeGreen
        FontStyle Bold
      }
    }
</style>

!include ws2.puml

hide <<FL1>>

title Products merged, FL2 and FL3 only

@enduml

Now what?

Well, not much to add here for today. Maybe some more notes.

Bigger Topologies

In this post we’ve used a small example. The approach does also work for bigger system architectures. The Flight Levels workshops use the Dronez company, a systems architecture with way more contributors. However, the general approach is the very same: Have decentralized diagrams for the contributing work systems, compose a systems architecture view out of these.

@startuml

!define fllib https://raw.githubusercontent.com/worksystems-design/plantuml-flightlevels-lib/refs/heads/main/defs
!include fllib/fl-wst.iuml
!include fllib/fl-wst.iuml!wsd.branding

' Internal Platforms
!include software platform.puml
!include propeller platform.puml

' Product Work Systems
!include maxair.puml
!include 3p.puml
!include 4p.puml 
!include 5p.puml

' Supply Chain functions
!include assembly.puml

' Operational Portfolio level
!include operational portfolio.puml

remove <<FL1>>

@enduml

For completeness, the full view here:

And Miro?

You might ask: Can I do this with Miro? Well, yes and no. Miro has recently introduced a feature called Synced copies. I tried to use it in context of a client’s systems topology. It kind of worked, but it has limitations. The resulting diagrams look a bit strange because synced copies are available on frame level only.

Advanced views like changing styles, showing deltas, filter by flight levels or other aspects are not possible. Furthermore, you need discipline to name the boards consistently, have a consistent structure of spaces and teams and eventually all the permissions set correctly. Not to easy to achieve in a corporate setting.

Didn’t try Synced copies in combination with another feature - Layers. This would be another experiment to try with Miro.

What’s next?

I’m currently working on visualizing events and activities using PlantUML. Similar approach, they should be composable, they should be easy to maintain, and add value when designing, analyzing and evolving work systems together.

Btw., all sources used in this and related blog posts are available here: https://github.com/worksystems-design/plantuml-flightlevels-visualizations