C4

Classes in this package are mappings of the architecture model classes to the abstractions of the The C4 model for visualising software architecture.

The classes in this package do not introduce any new structural features (attributes or references) or operations, just new semantics. E.g. System and Container extend CompositeNode - they can have documentation, icon, incoming and outgoing connections, nested elements, … The difference between them is in definitions.

Demos

Internet Banking System

• Generated documentation sites with different Bootswatch themes:
  • Cerulean - can be used to publish the base line architecture - what is already deployed.
  • Sketchy - can be used to publish future architectures.
• Source code

Direct Generation

There is also a demo of documentation produced with “Direct Generation” approach explained in Visual communication continuum story (also in Resources):

• Site
• Sources

The direct generation approach is simpler and might be easier to get started with. It was designed to be compatible with semantic mapping explained here to simplify migration.

Basic demo

• Generated documentation sites with different Bootswatch themes:
  • Cerulean
  • Sketchy
• Source code

Quick Start

• Start Drawio editor - in-browser, desktop (also drawio.io Diagrams in Microsoft Store), or VS Code extension.
• Create a new diagram from https://architecture.models.nasdanika.org/resources/c4-template.drawio template
• Add https://architecture.models.nasdanika.org/resources/C4.xml library
• Add elements from the C4 library above to the diagram. You may edit elements id’s or add semantic-id property to have meaningful (semantic) URL’s in generated documentation and meaningful identifiers for cross-referencing.
• Create additional diagram pages for diagram elements with internal structures. E.g. a System consisting of Containers. Link the diagram elements to their respective pages. There can be multiple levels of diagram hierarchy.
• Add Context container from the C4 library to a sub-diargram page.
• Add children of the diagram element to the context container. E.g. containers to a system context container.
• Add diagram elements to link already defined elements. E.g. a Person. Remove type property and add selector property to link the diagram element to an already defined mapping of a diagram element to a semantic element. For example, getDocument().getModelElementById('user') would link a diagram element to another diagram element with id user. getDocument().getModelElementByProperty('semantic-id', 'personal-banking-customer') selects an element by its property value. It is also possible to do page-level selections: getDocument().getPageByXXX().getModelElementByXXX().
• Save the diagram.
• Use Nasdanika CLI app/model/site command or app/model/action command and then app/site command to generate documentation site.

Linking relationships

Relationships documentation can be accessed by clicking relationships on diagrams in generated documentation. To link relationships from Markdown use references/outgoingConnections/<id>/index.html URL relative to the relationship source. <id> stands for the semantic id, which defaults to the diagram element id if not set via semantic-id property.

Sample command

nsd app model site -f C:\_temp\c4\c4.drawio C:\_temp\c4\site --root-action-text="Nasdanika C4 Model Demos"

Resources

• Visual communication continuum story introduces “Direct Generation” of documentation from diagrams, which is simpler than semantic mapping. I also compares direct generation with semantic mapping.
• Architecture As Code story explains high level concepts and possible applications of the architecture model.
• Beyond Diagrams book provides a detailed explanation how to map Drawio diagrams to semantic models, make them executable, … The book is still work in progress, more installments to come!
• Reference documentation