In this module, you will learn how to:
- Document a
software modelwithcomment - Enrich a
software modelwithtagto convey semantic - Customize visualization thanks to
theme - Enrich a
software modelwithurlto link with external resources
⌛ Estimated time to complete: 15 min
As part of the code base, software model obeys same rule, namely all can be enforced by the underlying language - here DSL - has to be. If we need more, don't be afraid to fallback to plain old comment #. As workspace now lands in our repository, one obvious one is to add copyright information.
✏️ Add copyright information.
📙 REVEAL THE ANSWER
+# © 2022 DAEDALUS, Inc. Unauthorized use, distribution, or duplication is prohibited.
workspace "MILA" "Multiple Images Lightweight Acquisition" {
}One may have noticed there is some asymetry on the software model we are shaping that could be better materiliazed, namely the fact that it involves 2 different software systems that does not play the same role: MILA is the main one, Icarus is a satellite one. It could be obvious for folks regularly involved in the project, but remember that audience is heterogenous and making stuff explicit does not harm. Let's see how one could improve this by introducing a new dimension to our software model via tag.
✏️ Fill the tag field of Icarus software system.
In case you previously cleared every placeholder, and are now lost on picking back the right one, simply hover over the C4 softwareSystem keyword, and Cornifer will provide all information you are looking for. Tag can be whatever you want, e.g. 123, a b c & #aaaBbbCccc are all valid. Even if no convention is enforced, you might find it helpful to prefix all your tags with # and use single word tags, like we are used to for other applications such as twitter.
📙 REVEAL THE ANSWER
model {
mila = softwareSystem "MILA" "Provides [...]" "" {
}
- icarus = softwareSystem "Icarus" "Provides [...]" "" {
+ icarus = softwareSystem "Icarus" "Provides [...]" "#external" {
}
}
}This tag becomes now actionable from the theme side to fine-tune downstream rendering.
✏️ Amend theme.dslf to handle the tag you introduce above. f you were not able to complete the previous exercise for whatever reason, use the #external tag for now.
📙 REVEAL THE ANSWER
views {
styles {
element "Software System" {
background #CFE4FF
stroke #0C7CBA
strokeWidth 8
}
+ element "#external" {
+ background #F5F5F5
+ stroke #666666
+ strokeWidth 8
+ }
}
}At this point we name our tag #external, as it will be used to tag elements we consider as external regarding the software model we are crafting, MILA. This has nothing to do with the fact an element belongs - or not - to the same group. Imagine you are looking on a geographic map for insights regarding bordering regions. Regions that belong to the same country and adjacent countries are considered external. They are there to give spatial context, but are usually grayed out when region insights we are focusing on is colored.
Consider Grand Est French region as our current software model. Both Hauts-de-France French region and external countries like Schweiz are considered external, the same way. They provide context but should not steal the focus.
✏️ Save your workspace, and refresh the browser page.
As a software system, Icarus will inherit from matching built-in Software System style. But as we provide an extra #external tag, style will be amended accordingly and some aspects superseded.
| C4.L | C4.1 |
|---|---|
 |
 |
Regarding the tag precedence algorithm, last one wins:
# Built-in 'Software System' style is applied
cornifer = softwareSystem "Cornifer" "" "" {}
# Apply built-in 'Software System' style, then '#tag1' one.
# If some traits are shared by styles, '#tag1' ones supersede those from built-in 'Software System'
cornifer = softwareSystem "Cornifer" "" "#tag1" {}
# Apply built-in 'Software System' style, then '#tag1' one, then '#tag2' one.
# If some traits are shared by styles, '#tag1' ones supersede those from built-in 'Software System',
# and '#tag2' ones supersede those from both built-in 'Software System' & '#tag1'
cornifer = softwareSystem "Cornifer" "" "#tag1,#tag2" {}
We materialize coupling with external software system, here Icarus, leveraging out of scope (gray color) semantic. The intent is to provide context, not to lose focus. We are there to talk about MILA.
Hyperlinks are great to navigate complex topic, and software model makes no exception:
- Your audience may not be familiar with all content
- Some taxonomy may be ambiguous
- You would like to smooth or speed up entry points by providing contextual & meaningful links instead of generic ones
- ...
Whatever the reason, feel free to leverage url keyword to enrich your model.
✏️ Add url to MILA software system.
📙 REVEAL THE ANSWER
model {
matt = person "Material scientist" "Leverages [...]" ""
simon = person "Simulation engineer" "Crafts [...]" ""
mila = softwareSystem "MILA" "Provides [...]" "" {
url https://github.com/rvr06/c4-bootcamp/blob/main/stage%2000/specs.md
}
icarus = softwareSystem "Icarus" "Provides [...]" "#external" {
}
}Doing so will enrich matching element within views with an extra # symbol. Double clicking it will trigger the navigation. You can provide more than one link (like project website & project repository), but only the first one will be used for navigation.
Regarding the url precedence algorithm, last one wins:
cornifer = softwareSystem "Cornifer" "" "" {
url https://github.com/rvr06/c4-bootcamp/blob/main/stage%2000/specs.md
url https://github.com/rvr06/c4-bootcamp/
}
Whatever the one you pick, enriching your model is important as it allows .dsl reader to quickly access meaninfgul information, making your software model acting as an information hub.
📘 Completing this stage should lead to this final workspace.
You learn how to enrich your software model with metadata that can be consumed downstream by Structurizr engine to improve outcomes.
What about digging in a bit deeper in the next stage?