diff --git a/docs/building.md b/docs/building.md index 0d61b82..67ac366 100644 --- a/docs/building.md +++ b/docs/building.md @@ -1,6 +1,6 @@ # Building -To build this repo from the sources (you'll need `git` and Java 11+ installed)... +To build this repo from the sources (you'll need `git` and Java 17+ installed)... ``` git clone https://github.com/structurizr/dsl.git structurizr-dsl diff --git a/docs/cookbook/README.md b/docs/cookbook/README.md deleted file mode 100644 index 63063a6..0000000 --- a/docs/cookbook/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# Structurizr DSL cookbook - -Creating software architecture diagrams from a textual definition ("diagrams as code") is becoming more popular, -but if you have a collection of related diagrams, it's easy to introduce inconsistencies if you don't keep the many -diagram source files in sync. - -This cookbook is a tutorial guide to the Structurizr DSL, an open source tool for creating diagrams as code from -a single consistent model. This cookbook assumes that you're using the diagram renderer provided by the -[Structurizr cloud service](https://structurizr.com/help/cloud-service), -the [Structurizr on-premises installation](https://structurizr.com/help/on-premises), -or [Structurizr Lite](https://structurizr.com/help/lite). -Please note that some features (e.g. perspectives, element style shapes/icons, etc) may not be supported if you're -using one of the PlantUML/Mermaid/D2/DOT/etc export formats provided by the -[Structurizr CLI](https://github.com/structurizr/cli) and the [structurizr-export library](https://github.com/structurizr/export). - -## Table of contents - -- [Introduction](introduction) -- [Workspace](workspace) -- [Workspace extension](workspace-extension) -- [Implied relationships](implied-relationships) -- [System Context view](system-context-view) -- [Container view](container-view) -- [Container view (spanning multiple software systems)](container-view-for-multiple-software-systems) -- [Component view](component-view) -- [Shared components](shared-components) -- [Image view](image-view) -- [Filtered view](filtered-view) -- [Dynamic view](dynamic-view) -- [Dynamic view with parallel sequences](dynamic-view-parallel) -- [Deployment view](deployment-view) -- [Amazon Web Services](amazon-web-services) -- [Deployment groups](deployment-groups) -- [Element styles](element-styles) -- [Relationship styles](relationship-styles) -- [Themes](themes) -- [Groups](groups) -- [Perspectives](perspectives) -- [Scripts](scripts) -- [DSL and code (hybrid usage pattern)](dsl-and-code) \ No newline at end of file diff --git a/docs/cookbook/amazon-web-services/README.md b/docs/cookbook/amazon-web-services/README.md deleted file mode 100644 index 891ef52..0000000 --- a/docs/cookbook/amazon-web-services/README.md +++ /dev/null @@ -1,129 +0,0 @@ -# Amazon Web Services - -A [deployment view](../deployment-view) can be used to model the deployment of your software system onto Amazon Web Services. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - live = deploymentEnvironment "Live" { - deploymentNode "Amazon Web Services" { - deploymentNode "US-East-1" { - route53 = infrastructureNode "Route 53" - elb = infrastructureNode "Elastic Load Balancer" - - deploymentNode "Amazon EC2" { - deploymentNode "Ubuntu Server" { - webApplicationInstance = containerInstance webapp - } - } - - deploymentNode "Amazon RDS" { - deploymentNode "MySQL" { - containerInstance database - } - } - } - } - - route53 -> elb "Forwards requests to" "HTTPS" - elb -> webApplicationInstance "Forwards requests to" "HTTPS" - } - } - - views { - deployment s live { - include * - autoLayout lr - } - } - -} -``` - -This DSL defines a deployment environment named `Live`, with a hierarchy of deployment nodes showing the various AWS services in use for deployment. It also defines some infrastructure nodes representing services that don't have any software systems/containers deployed onto them. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/amazon-web-services/example-1.dsl) - -The [pre-built Amazon Web Services theme](https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/amazon-web-services-2020.04.30/theme.json) can be used to add some colour, and make use of the AWS icon set. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - live = deploymentEnvironment "Live" { - deploymentNode "Amazon Web Services" { - tags "Amazon Web Services - Cloud" - - deploymentNode "US-East-1" { - tags "Amazon Web Services - Region" - - route53 = infrastructureNode "Route 53" { - tags "Amazon Web Services - Route 53" - } - elb = infrastructureNode "Elastic Load Balancer" { - tags "Amazon Web Services - Elastic Load Balancing" - } - - deploymentNode "Amazon EC2" { - tags "Amazon Web Services - EC2" - - deploymentNode "Ubuntu Server" { - webApplicationInstance = containerInstance webapp - } - } - - deploymentNode "Amazon RDS" { - tags "Amazon Web Services - RDS" - - deploymentNode "MySQL" { - tags "Amazon Web Services - RDS MySQL instance" - - containerInstance database - } - } - } - } - - route53 -> elb "Forwards requests to" "HTTPS" - elb -> webApplicationInstance "Forwards requests to" "HTTPS" - } - } - - views { - deployment s live { - include * - autoLayout lr - } - - theme https://static.structurizr.com/themes/amazon-web-services-2020.04.30/theme.json - } - -} -``` - -This DSL adds some element tags, and a reference to the Amazon Web Services theme. - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/amazon-web-services/example-2.dsl) - -Further styles can be added if desired too. - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/amazon-web-services/example-3.dsl) \ No newline at end of file diff --git a/docs/cookbook/amazon-web-services/example-1.dsl b/docs/cookbook/amazon-web-services/example-1.dsl deleted file mode 100644 index d86f262..0000000 --- a/docs/cookbook/amazon-web-services/example-1.dsl +++ /dev/null @@ -1,45 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - live = deploymentEnvironment "Live" { - deploymentNode "Amazon Web Services" { - deploymentNode "US-East-1" { - route53 = infrastructureNode "Route 53" - elb = infrastructureNode "Elastic Load Balancer" - - deploymentNode "Amazon EC2" { - deploymentNode "Ubuntu Server" { - webApplicationInstance = containerInstance webapp - } - } - - deploymentNode "Amazon RDS" { - deploymentNode "MySQL" { - containerInstance database - } - } - } - } - - route53 -> elb "Forwards requests to" "HTTPS" - elb -> webApplicationInstance "Forwards requests to" "HTTPS" - } - } - - views { - deployment s live { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/amazon-web-services/example-1.png b/docs/cookbook/amazon-web-services/example-1.png deleted file mode 100644 index 95eb016..0000000 Binary files a/docs/cookbook/amazon-web-services/example-1.png and /dev/null differ diff --git a/docs/cookbook/amazon-web-services/example-2.dsl b/docs/cookbook/amazon-web-services/example-2.dsl deleted file mode 100644 index 0c3b090..0000000 --- a/docs/cookbook/amazon-web-services/example-2.dsl +++ /dev/null @@ -1,61 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - live = deploymentEnvironment "Live" { - deploymentNode "Amazon Web Services" { - tags "Amazon Web Services - Cloud" - - deploymentNode "US-East-1" { - tags "Amazon Web Services - Region" - - route53 = infrastructureNode "Route 53" { - tags "Amazon Web Services - Route 53" - } - elb = infrastructureNode "Elastic Load Balancer" { - tags "Amazon Web Services - Elastic Load Balancing" - } - - deploymentNode "Amazon EC2" { - tags "Amazon Web Services - EC2" - - deploymentNode "Ubuntu Server" { - webApplicationInstance = containerInstance webapp - } - } - - deploymentNode "Amazon RDS" { - tags "Amazon Web Services - RDS" - - deploymentNode "MySQL" { - tags "Amazon Web Services - RDS MySQL instance" - - containerInstance database - } - } - } - } - - route53 -> elb "Forwards requests to" "HTTPS" - elb -> webApplicationInstance "Forwards requests to" "HTTPS" - } - } - - views { - deployment s live { - include * - autoLayout lr - } - - theme https://static.structurizr.com/themes/amazon-web-services-2020.04.30/theme.json - } - -} \ No newline at end of file diff --git a/docs/cookbook/amazon-web-services/example-2.png b/docs/cookbook/amazon-web-services/example-2.png deleted file mode 100644 index 4b79780..0000000 Binary files a/docs/cookbook/amazon-web-services/example-2.png and /dev/null differ diff --git a/docs/cookbook/amazon-web-services/example-3.dsl b/docs/cookbook/amazon-web-services/example-3.dsl deleted file mode 100644 index b4dc56b..0000000 --- a/docs/cookbook/amazon-web-services/example-3.dsl +++ /dev/null @@ -1,69 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - live = deploymentEnvironment "Live" { - deploymentNode "Amazon Web Services" { - tags "Amazon Web Services - Cloud" - - deploymentNode "US-East-1" { - tags "Amazon Web Services - Region" - - route53 = infrastructureNode "Route 53" { - tags "Amazon Web Services - Route 53" - } - elb = infrastructureNode "Elastic Load Balancer" { - tags "Amazon Web Services - Elastic Load Balancing" - } - - deploymentNode "Amazon EC2" { - tags "Amazon Web Services - EC2" - - deploymentNode "Ubuntu Server" { - webApplicationInstance = containerInstance webapp - } - } - - deploymentNode "Amazon RDS" { - tags "Amazon Web Services - RDS" - - deploymentNode "MySQL" { - tags "Amazon Web Services - RDS MySQL instance" - - containerInstance database - } - } - } - } - - route53 -> elb "Forwards requests to" "HTTPS" - elb -> webApplicationInstance "Forwards requests to" "HTTPS" - } - } - - views { - deployment s live { - include * - autoLayout lr - } - - styles { - element "Element" { - shape RoundedBox - background #ffffff - color #000000 - } - } - - theme https://static.structurizr.com/themes/amazon-web-services-2020.04.30/theme.json - } - -} \ No newline at end of file diff --git a/docs/cookbook/amazon-web-services/example-3.png b/docs/cookbook/amazon-web-services/example-3.png deleted file mode 100644 index 6d59392..0000000 Binary files a/docs/cookbook/amazon-web-services/example-3.png and /dev/null differ diff --git a/docs/cookbook/component-view/README.md b/docs/cookbook/component-view/README.md deleted file mode 100644 index 0ea8ef7..0000000 --- a/docs/cookbook/component-view/README.md +++ /dev/null @@ -1,41 +0,0 @@ -# Component view - -A [component view](https://c4model.com/#ComponentDiagram) allows you to zoom-in to a container, to see the components that reside inside it. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" { - c1 = component "Component 1" - c2 = component "Component 2" - } - database = container "Database" - } - - u -> c1 "Uses" - c1 -> c2 "Uses" - c2 -> database "Reads from and writes to" - } - - views { - component webapp { - include * - autoLayout lr - } - } - -} -``` - -This DSL defines a component view for the container `webapp`, and `include *` includes the default set of model elements for the view. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/component-view/example-1.dsl) - -Component views can be rendered using the Structurizr cloud service/on-premises installation or exported to a number of other formats via the [Structurizr CLI export command](https://github.com/structurizr/cli/blob/master/docs/export.md). - -## Links - -- [DSL language reference - component](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#component-view) \ No newline at end of file diff --git a/docs/cookbook/component-view/example-1.dsl b/docs/cookbook/component-view/example-1.dsl deleted file mode 100644 index 49fa9a6..0000000 --- a/docs/cookbook/component-view/example-1.dsl +++ /dev/null @@ -1,25 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" { - c1 = component "Component 1" - c2 = component "Component 2" - } - database = container "Database" - } - - u -> c1 "Uses" - c1 -> c2 "Uses" - c2 -> database "Reads from and writes to" - } - - views { - component webapp { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/component-view/example-1.png b/docs/cookbook/component-view/example-1.png deleted file mode 100644 index 4ede518..0000000 Binary files a/docs/cookbook/component-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/container-view-for-multiple-software-systems/README.md b/docs/cookbook/container-view-for-multiple-software-systems/README.md deleted file mode 100644 index 32410eb..0000000 --- a/docs/cookbook/container-view-for-multiple-software-systems/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# Container view (spanning multiple software systems) - -By default, the `include *` statement, when used inside a container view definition, will include all of the containers -inside the software system in scope, along with any external software system dependencies. -For example, the following DSL will generate the diagram below. - -``` -workspace { - - model { - s1 = softwareSystem "Software System 1" { - c1 = container "Container 1" - } - - s2 = softwareSystem "Software System 2" { - c2 = container "Container 2" - } - - c1 -> c2 - } - - views { - container s1 { - include * - autoLayout lr - } - } - -} -``` - -[![](example-1.png)](https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/container-view-for-multiple-software-systems/example-1.dsl) - -While sufficient for many purposes, there may be times when you want to show the dependency between the two containers, each of which resides in a -separate software system. -To do this, you can modify the `include` statement, as shown in the example below. - -``` -workspace { - - model { - s1 = softwareSystem "Software System 1" { - c1 = container "Container 1" - } - - s2 = softwareSystem "Software System 2" { - c2 = container "Container 2" - } - - c1 -> c2 - } - - views { - container s1 { - include c1 c2 - autoLayout lr - } - } - -} -``` - -This in turn will now show the two containers. - -[![](example-2.png)](https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/container-view-for-multiple-software-systems/example-2.dsl) - -If you'd rather not specify each container individually, you could utilise an [expression](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#expressions) -and replace the `include` statement with one of the following: - -- `include element.type==container` -- `include element.parent==s1 element.parent==s2` - -## Links - -- [DSL language reference - container](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#container-view) -- [DSL language reference - Expressions](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#expressions) \ No newline at end of file diff --git a/docs/cookbook/container-view-for-multiple-software-systems/example-1.dsl b/docs/cookbook/container-view-for-multiple-software-systems/example-1.dsl deleted file mode 100644 index a794cf6..0000000 --- a/docs/cookbook/container-view-for-multiple-software-systems/example-1.dsl +++ /dev/null @@ -1,22 +0,0 @@ -workspace { - - model { - s1 = softwareSystem "Software System 1" { - c1 = container "Container 1" - } - - s2 = softwareSystem "Software System 2" { - c2 = container "Container 2" - } - - c1 -> c2 - } - - views { - container s1 { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/container-view-for-multiple-software-systems/example-1.png b/docs/cookbook/container-view-for-multiple-software-systems/example-1.png deleted file mode 100644 index dbfd569..0000000 Binary files a/docs/cookbook/container-view-for-multiple-software-systems/example-1.png and /dev/null differ diff --git a/docs/cookbook/container-view-for-multiple-software-systems/example-2.dsl b/docs/cookbook/container-view-for-multiple-software-systems/example-2.dsl deleted file mode 100644 index a339d7a..0000000 --- a/docs/cookbook/container-view-for-multiple-software-systems/example-2.dsl +++ /dev/null @@ -1,22 +0,0 @@ -workspace { - - model { - s1 = softwareSystem "Software System 1" { - c1 = container "Container 1" - } - - s2 = softwareSystem "Software System 2" { - c2 = container "Container 2" - } - - c1 -> c2 - } - - views { - container s1 { - include c1 c2 - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/container-view-for-multiple-software-systems/example-2.png b/docs/cookbook/container-view-for-multiple-software-systems/example-2.png deleted file mode 100644 index 571eabd..0000000 Binary files a/docs/cookbook/container-view-for-multiple-software-systems/example-2.png and /dev/null differ diff --git a/docs/cookbook/container-view/README.md b/docs/cookbook/container-view/README.md deleted file mode 100644 index 025795c..0000000 --- a/docs/cookbook/container-view/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# Container view - -A [container view](https://c4model.com/#ContainerDiagram) allows you to zoom-in to the software system shown on a system context view, to see the applications and data stores (what the C4 model refers to as "containers") that reside inside it. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - database = container "Database" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - } - - views { - container s { - include * - autoLayout lr - } - } - -} -``` - -This DSL defines a container view for the software system `s`, and `include *` includes the default set of model elements for the view. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/container-view/example-1.dsl) - -Container views can be rendered using the Structurizr cloud service/on-premises installation or exported to a number of other formats via the [Structurizr CLI export command](https://github.com/structurizr/cli/blob/master/docs/export.md). - -## Links - -- [DSL language reference - container](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#container-view) \ No newline at end of file diff --git a/docs/cookbook/container-view/example-1.dsl b/docs/cookbook/container-view/example-1.dsl deleted file mode 100644 index ff1d03e..0000000 --- a/docs/cookbook/container-view/example-1.dsl +++ /dev/null @@ -1,21 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - database = container "Database" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - } - - views { - container s { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/container-view/example-1.png b/docs/cookbook/container-view/example-1.png deleted file mode 100644 index 1a1ac8c..0000000 Binary files a/docs/cookbook/container-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/deployment-groups/README.md b/docs/cookbook/deployment-groups/README.md deleted file mode 100644 index 95ade43..0000000 --- a/docs/cookbook/deployment-groups/README.md +++ /dev/null @@ -1,97 +0,0 @@ -# Deployment groups - -Imagine that you have a service comprised of an API and a database scheme, which are deployed together onto a single server. -Now let's say there are two instances of this entire service, each deployed onto a separate server. - -``` -workspace { - - model { - softwareSystem = softwareSystem "Software System" { - database = container "Database Schema" - api = container "Service API" { - -> database "Uses" - } - } - - production = deploymentEnvironment "Production" { - deploymentNode "Server 1" { - containerInstance api - deploymentNode "Database Server" { - containerInstance database - } - } - deploymentNode "Server 2" { - containerInstance api - deploymentNode "Database Server" { - containerInstance database - } - } - } - } - - views { - deployment * production { - include * - autolayout - } - } - -} -``` - -The container instance to container instance relationships are based upon the container to container relationships -defined in the static structure part of the model. -While this works out of the box in many cases, here we can see that the "Service API" on "Server 1" has a connection to the "Database Schema" on "Server 2", and vice versa. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/deployment-groups/example-1.dsl) - -If this is not the desired behaviour, you can use the "deployment group" feature, which -provides a way to group software system/container instances and restrict how relationships are created between them. -For example, we can create two deployment groups, and place one instance of both the "Service API" and "Database Schema" in each. - -``` -workspace { - - model { - softwareSystem = softwareSystem "Software System" { - database = container "Database Schema" - api = container "Service API" { - -> database "Uses" - } - } - - production = deploymentEnvironment "Production" { - serviceInstance1 = deploymentGroup "Service instance 1" - serviceInstance2 = deploymentGroup "Service instance 2" - - deploymentNode "Server 1" { - containerInstance api serviceInstance1 - deploymentNode "Database Server" { - containerInstance database serviceInstance1 - } - } - deploymentNode "Server 2" { - containerInstance api serviceInstance2 - deploymentNode "Database Server" { - containerInstance database serviceInstance2 - } - } - } - } - - views { - deployment * production { - include * - autolayout - } - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/deployment-groups/example-2.dsl) - -## Links - -- [DSL language reference - deploymentGroup](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#deploymentGroup) \ No newline at end of file diff --git a/docs/cookbook/deployment-groups/example-1.dsl b/docs/cookbook/deployment-groups/example-1.dsl deleted file mode 100644 index d1f8745..0000000 --- a/docs/cookbook/deployment-groups/example-1.dsl +++ /dev/null @@ -1,34 +0,0 @@ -workspace { - - model { - softwareSystem = softwareSystem "Software System" { - database = container "Database Schema" - api = container "Service API" { - -> database "Uses" - } - } - - production = deploymentEnvironment "Production" { - deploymentNode "Server 1" { - containerInstance api - deploymentNode "Database Server" { - containerInstance database - } - } - deploymentNode "Server 2" { - containerInstance api - deploymentNode "Database Server" { - containerInstance database - } - } - } - } - - views { - deployment * production { - include * - autolayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/deployment-groups/example-1.png b/docs/cookbook/deployment-groups/example-1.png deleted file mode 100644 index f04b003..0000000 Binary files a/docs/cookbook/deployment-groups/example-1.png and /dev/null differ diff --git a/docs/cookbook/deployment-groups/example-2.dsl b/docs/cookbook/deployment-groups/example-2.dsl deleted file mode 100644 index f30583d..0000000 --- a/docs/cookbook/deployment-groups/example-2.dsl +++ /dev/null @@ -1,37 +0,0 @@ -workspace { - - model { - softwareSystem = softwareSystem "Software System" { - database = container "Database Schema" - api = container "Service API" { - -> database "Uses" - } - } - - production = deploymentEnvironment "Production" { - serviceInstance1 = deploymentGroup "Service instance 1" - serviceInstance2 = deploymentGroup "Service instance 2" - - deploymentNode "Server 1" { - containerInstance api serviceInstance1 - deploymentNode "Database Server" { - containerInstance database serviceInstance1 - } - } - deploymentNode "Server 2" { - containerInstance api serviceInstance2 - deploymentNode "Database Server" { - containerInstance database serviceInstance2 - } - } - } - } - - views { - deployment * production { - include * - autolayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/deployment-groups/example-2.png b/docs/cookbook/deployment-groups/example-2.png deleted file mode 100644 index 882ac26..0000000 Binary files a/docs/cookbook/deployment-groups/example-2.png and /dev/null differ diff --git a/docs/cookbook/deployment-view/README.md b/docs/cookbook/deployment-view/README.md deleted file mode 100644 index 0472152..0000000 --- a/docs/cookbook/deployment-view/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Deployment view - -A [deployment view](https://c4model.com/#DeploymentDiagram) allows you to show how software systems and containers are deployed, by showing the mapping of software system and container _instances_ onto deployment nodes. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - development = deploymentEnvironment "Development" { - deploymentNode "Developer Laptop" { - containerInstance webapp - deploymentNode "MySQL" { - containerInstance database - } - } - } - } - - views { - deployment * development { - include * - autoLayout lr - } - } - -} -``` - -This DSL defines a deployment environment named `Development`, with instances of the `webapp` and `database` containers deployed onto some deployment nodes. It also defines a deployment view for this deployment environment, and `include *` includes the default set of model elements for the view. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/deployment-view/example-1.dsl) - -Deployment views can be rendered using the Structurizr cloud service/on-premises installation or exported to a number of other formats via the [Structurizr CLI export command](https://github.com/structurizr/cli/blob/master/docs/export.md). - -## Links - -- [DSL language reference - deployment](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#deployment-view) \ No newline at end of file diff --git a/docs/cookbook/deployment-view/example-1.dsl b/docs/cookbook/deployment-view/example-1.dsl deleted file mode 100644 index 5697c30..0000000 --- a/docs/cookbook/deployment-view/example-1.dsl +++ /dev/null @@ -1,30 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" "" "Spring Boot" - database = container "Database" "" "Relational database schema" - } - - u -> webapp "Uses" - webapp -> database "Reads from and writes to" - - development = deploymentEnvironment "Development" { - deploymentNode "Developer Laptop" { - containerInstance webapp - deploymentNode "MySQL" { - containerInstance database - } - } - } - } - - views { - deployment * development { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/deployment-view/example-1.png b/docs/cookbook/deployment-view/example-1.png deleted file mode 100644 index ee4fdd8..0000000 Binary files a/docs/cookbook/deployment-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/dsl-and-code/README.md b/docs/cookbook/dsl-and-code/README.md deleted file mode 100644 index c7edce6..0000000 --- a/docs/cookbook/dsl-and-code/README.md +++ /dev/null @@ -1,82 +0,0 @@ -# DSL and code - -It's possible to use both the DSL and a code-based library together - perhaps you want to define a basic model via the DSL, and use automatic extraction to add components to the model. To do this, define your workspace using the DSL as normal, for example: - -``` -workspace { - - model { - s = softwareSystem "Software System" { - webapp = container "Web Application" - database = container "Database" { - webapp -> this "Reads from and writes to" - } - } - } - - views { - container s { - include * - autoLayout lr - } - } - -} -``` - -## Java - -Since the DSL parser is written in Java, you can use it directly by adding a dependency on the `structurizr-dsl` library, which is available on [Maven Central](https://search.maven.org/artifact/com.structurizr/structurizr-dsl): - -- groupId: `com.structurizr` -- artifactId: `structurizr-dsl` - -You can then write a Java program that parses your DSL definition, and extends the workspace further; for example: - -``` -StructurizrDslParser parser = new StructurizrDslParser(); -parser.parse(new File("workspace.dsl")); - -Workspace workspace = parser.getWorkspace(); -Container webApplication = workspace.getModel().getSoftwareSystemWithName("Software System").getContainerWithName("Web Application"); - -// add components manually or via automatic extraction -... - -// add a component view -ComponentView componentView = workspace.getViews().createComponentView(webApplication, "Components", "Description"); -componentView.addDefaultElements(); -componentView.enableAutomaticLayout(); -``` - -Please note that the Structurizr for Java library is designed to be *append only*, so it's not possible to remove/modify elements/relationships that already exist in the model. - -## Other languages - -Ports of the "Structurizr for Java" library are available for a number of other programming languages - see [https://structurizr.org/#authoring](https://structurizr.org/#authoring) for links. Although you can't use the DSL parser directly, you can achieve the same effect with the following steps: - -### 1. Convert your DSL workspace to the JSON format - -This can be done using the [Structurizr CLI export command](https://github.com/structurizr/cli/blob/master/docs/export.md): - -``` -structurizr export -workspace workspace.dsl -format json -``` - -### 2. Load the JSON file, and add to the workspace - -A Structurizr for .NET version of the above example is as follows: - -``` -FileInfo fileInfo = new FileInfo("workspace.json"); -Workspace workspace = WorkspaceUtils.LoadWorkspaceFromJson(fileInfo); -Container webApplication = workspace.Model.GetSoftwareSystemWithName("Software System").GetContainerWithName("Web Application"); - -// add components manually or via automatic extraction -... - -// add a component view -ComponentView componentView = workspace.Views.CreateComponentView(webApplication, "Components", "Description"); -componentView.AddDefaultElements(); -componentView.EnableAutomaticLayout(); -``` \ No newline at end of file diff --git a/docs/cookbook/dynamic-view-parallel/README.md b/docs/cookbook/dynamic-view-parallel/README.md deleted file mode 100644 index 80ba602..0000000 --- a/docs/cookbook/dynamic-view-parallel/README.md +++ /dev/null @@ -1,49 +0,0 @@ -# Dynamic view with parallel sequences - -Dynamic views can also be used to show parallel sequences of interactions, to indicate some degree of concurrency. -To do this, you can use the DSL block syntax `{` and `}` to define parallel sequences. - -``` -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - d = softwareSystem "D" - e = softwareSystem "E" - - a -> b - b -> c - b -> d - b -> e - } - - views { - - dynamic * { - a -> b "Makes a request to" - { - { - b -> c "Gets data from" - } - { - b -> d "Gets data from" - } - } - b -> e "Sends data to" - - autoLayout - } - } - -} -``` - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/dynamic-view-parallel/example-1.dsl) - -Please note that support for parallel sequences via the DSL is relatively limited. - -## Links - -- [DSL language reference - dynamic](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#dynamic-view) \ No newline at end of file diff --git a/docs/cookbook/dynamic-view-parallel/example-1.dsl b/docs/cookbook/dynamic-view-parallel/example-1.dsl deleted file mode 100644 index 8d7d39e..0000000 --- a/docs/cookbook/dynamic-view-parallel/example-1.dsl +++ /dev/null @@ -1,34 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - d = softwareSystem "D" - e = softwareSystem "E" - - a -> b - b -> c - b -> d - b -> e - } - - views { - - dynamic * { - a -> b "Makes a request to" - { - { - b -> c "Gets data from" - } - { - b -> d "Gets data from" - } - } - b -> e "Sends data to" - - autoLayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/dynamic-view-parallel/example-1.png b/docs/cookbook/dynamic-view-parallel/example-1.png deleted file mode 100644 index 7a556d0..0000000 Binary files a/docs/cookbook/dynamic-view-parallel/example-1.png and /dev/null differ diff --git a/docs/cookbook/dynamic-view/README.md b/docs/cookbook/dynamic-view/README.md deleted file mode 100644 index 8f1d9fd..0000000 --- a/docs/cookbook/dynamic-view/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# Dynamic view - -A [dynamic view](https://c4model.com/#DynamicDiagram) allows you to show a subset of the elements in a model, and the relationships between them, in order to describe how a particular use case/story/feature works. Dynamic views show ordered __instances__ of relationships, therefore reducing the number of relationships you need to define in the static model - see [Modelling multiple relationships](https://dev.to/simonbrown/modelling-multiple-relationships-51bf) for more. - -``` -workspace { - - model { - customer = person "Customer" - onlineBookStore = softwareSystem "Online book store" { - webapp = container "Web Application" - database = container "Database" - } - - customer -> webapp "Browses and makes purchases using" - webapp -> database "Reads from and writes to" - } - - views { - container onlineBookStore { - include * - autoLayout lr - } - - dynamic onlineBookStore { - title "Request past orders feature" - customer -> webapp "Requests past orders from" - webapp -> database "Queries for orders using" - autoLayout lr - } - - dynamic onlineBookStore { - title "Browse top 20 books feature" - customer -> webapp "Requests the top 20 books from" - webapp -> database "Queries the top 20 books using" - autoLayout lr - } - } - -} -``` - -This DSL defines three views: - -1. A container view showing the user and containers - notice how the relationship between the user and the web application is quite general ("Browses and makes purchases using"). -2. A dynamic view for the "request past orders" feature. -2. A dynamic view for the "browse top 20 books" feature. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/dynamic-view/example-1.dsl) - -## Links - -- [DSL language reference - dynamic](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#dynamic-view) \ No newline at end of file diff --git a/docs/cookbook/dynamic-view/example-1.dsl b/docs/cookbook/dynamic-view/example-1.dsl deleted file mode 100644 index e20a5df..0000000 --- a/docs/cookbook/dynamic-view/example-1.dsl +++ /dev/null @@ -1,35 +0,0 @@ -workspace { - - model { - customer = person "Customer" - onlineBookStore = softwareSystem "Online book store" { - webapp = container "Web Application" - database = container "Database" - } - - customer -> webapp "Browses and makes purchases using" - webapp -> database "Reads from and writes to" - } - - views { - container onlineBookStore { - include * - autoLayout lr - } - - dynamic onlineBookStore { - title "Request past orders feature" - customer -> webapp "Requests past orders from" - webapp -> database "Queries for orders using" - autoLayout lr - } - - dynamic onlineBookStore { - title "Browse top 20 books feature" - customer -> webapp "Requests the top 20 books from" - webapp -> database "Queries the top 20 books using" - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/dynamic-view/example-1.png b/docs/cookbook/dynamic-view/example-1.png deleted file mode 100644 index 52de158..0000000 Binary files a/docs/cookbook/dynamic-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/element-styles/README.md b/docs/cookbook/element-styles/README.md deleted file mode 100644 index ca30837..0000000 --- a/docs/cookbook/element-styles/README.md +++ /dev/null @@ -1,88 +0,0 @@ -# Element styles - -By default all elements are styled as grey boxes. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/element-styles/example-1.dsl) - -## Styling all elements - -To change the style for all elements, add an element style for the `Element` tag. - -``` -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Element" { - background #1168bd - color #ffffff - shape RoundedBox - } - } - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/element-styles/example-2.dsl) - -## Styling individual elements - -To change the style of an individual element: - -1. Tag the element. -2. Add an element style for that tag. - -``` -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Tag 1" { - background #1168bd - color #ffffff - shape RoundedBox - } - } - } - -} -``` - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/element-styles/example-3.dsl) - -## Notes - -Please note that element styles are designed to work with the Structurizr cloud service/on-premises installation, and may not be fully supported by the PlantUML, Mermaid, etc export formats. - -- [DSL language reference - styles - element](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#element-style) \ No newline at end of file diff --git a/docs/cookbook/element-styles/example-1.dsl b/docs/cookbook/element-styles/example-1.dsl deleted file mode 100644 index 42e1361..0000000 --- a/docs/cookbook/element-styles/example-1.dsl +++ /dev/null @@ -1,19 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/element-styles/example-1.png b/docs/cookbook/element-styles/example-1.png deleted file mode 100644 index abde92f..0000000 Binary files a/docs/cookbook/element-styles/example-1.png and /dev/null differ diff --git a/docs/cookbook/element-styles/example-2.dsl b/docs/cookbook/element-styles/example-2.dsl deleted file mode 100644 index 1873454..0000000 --- a/docs/cookbook/element-styles/example-2.dsl +++ /dev/null @@ -1,27 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Element" { - background #1168bd - color #ffffff - shape RoundedBox - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/element-styles/example-2.png b/docs/cookbook/element-styles/example-2.png deleted file mode 100644 index 834bd90..0000000 Binary files a/docs/cookbook/element-styles/example-2.png and /dev/null differ diff --git a/docs/cookbook/element-styles/example-3.dsl b/docs/cookbook/element-styles/example-3.dsl deleted file mode 100644 index 1a0176c..0000000 --- a/docs/cookbook/element-styles/example-3.dsl +++ /dev/null @@ -1,29 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Tag 1" { - background #1168bd - color #ffffff - shape RoundedBox - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/element-styles/example-3.png b/docs/cookbook/element-styles/example-3.png deleted file mode 100644 index dbae5e8..0000000 Binary files a/docs/cookbook/element-styles/example-3.png and /dev/null differ diff --git a/docs/cookbook/filtered-view/README.md b/docs/cookbook/filtered-view/README.md deleted file mode 100644 index 7bcbfa1..0000000 --- a/docs/cookbook/filtered-view/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Filtered view - -A [filtered view](https://structurizr.com/help/filtered-views) represents "a view on top of another view", which can be used to filter (`include` or `exclude`) specific elements and/or relationships, based upon their tag. Consider the following workspace definition: - -``` -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - c = softwareSystem "C" { - tags "Tag 3" - } - - a -> b - b -> c - } - - views { - systemLandscape "landscape" { - include * - autolayout lr - } - } - -} -``` - -This DSL defines three software systems with relationships between them, and a system landscape view showing those software systems. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/filtered-view/example-1.dsl) - -The filtered view feature can be used to define views on top of this system landscape view. For example, the following DSL defines two filtered views: - -``` -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - c = softwareSystem "C" { - tags "Tag 3" - } - - a -> b - b -> c - } - - views { - systemLandscape "landscape" { - include * - autolayout lr - } - - filtered "landscape" include "Tag 1,Tag 2,Relationship" "landscape1" - filtered "landscape" exclude "Tag 1" "landscape2" - } - -} -``` - -The first of these filtered views includes all elements/relationships that are tagged `Tag 1`, `Tag 2`, or `Relationship`. - -``` -filtered "landscape" include "Tag 1,Tag 2,Relationship" "landscape1" -``` - -[![](example-2-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/filtered-view/example-2.dsl&view=landscape1) - -And the second excludes all elements/relationships that are tagged `Tag 1`. - -``` -filtered "landscape" exclude "Tag 1" "landscape2" -``` - -[![](example-2-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/filtered-view/example-2.dsl&view=landscape2) - -When using filtered views, you'll notice that the original "base view" no longer shows in the list of viewable diagrams. This is by design. If you'd like to see the base view, you will need to create another filtered view that shows all elements and relationships. For example: - -``` -filtered "landscape" include "Element,Relationship" "landscape-all" -``` - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/filtered-view/example-3.dsl&view=landscape-all) - -## Links - -- [DSL language reference - filtered](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#filtered-view) diff --git a/docs/cookbook/filtered-view/example-1.dsl b/docs/cookbook/filtered-view/example-1.dsl deleted file mode 100644 index 59e22b7..0000000 --- a/docs/cookbook/filtered-view/example-1.dsl +++ /dev/null @@ -1,25 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - c = softwareSystem "C" { - tags "Tag 3" - } - - a -> b - b -> c - } - - views { - systemLandscape "landscape" { - include * - autolayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/filtered-view/example-1.png b/docs/cookbook/filtered-view/example-1.png deleted file mode 100644 index f0f1481..0000000 Binary files a/docs/cookbook/filtered-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/filtered-view/example-2-1.png b/docs/cookbook/filtered-view/example-2-1.png deleted file mode 100644 index 4e7e379..0000000 Binary files a/docs/cookbook/filtered-view/example-2-1.png and /dev/null differ diff --git a/docs/cookbook/filtered-view/example-2-2.png b/docs/cookbook/filtered-view/example-2-2.png deleted file mode 100644 index d8f1238..0000000 Binary files a/docs/cookbook/filtered-view/example-2-2.png and /dev/null differ diff --git a/docs/cookbook/filtered-view/example-2.dsl b/docs/cookbook/filtered-view/example-2.dsl deleted file mode 100644 index e297422..0000000 --- a/docs/cookbook/filtered-view/example-2.dsl +++ /dev/null @@ -1,28 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - c = softwareSystem "C" { - tags "Tag 3" - } - - a -> b - b -> c - } - - views { - systemLandscape "landscape" { - include * - autolayout lr - } - - filtered "landscape" include "Tag 1,Tag 2,Relationship" "landscape1" - filtered "landscape" exclude "Tag 1" "landscape2" - } - -} \ No newline at end of file diff --git a/docs/cookbook/filtered-view/example-3.dsl b/docs/cookbook/filtered-view/example-3.dsl deleted file mode 100644 index 13c2840..0000000 --- a/docs/cookbook/filtered-view/example-3.dsl +++ /dev/null @@ -1,29 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - c = softwareSystem "C" { - tags "Tag 3" - } - - a -> b - b -> c - } - - views { - systemLandscape "landscape" { - include * - autolayout lr - } - - filtered "landscape" include "Tag 1,Tag 2,Relationship" "landscape1" - filtered "landscape" exclude "Tag 1" "landscape2" - filtered "landscape" include "Element,Relationship" "landscape-all" - } - -} \ No newline at end of file diff --git a/docs/cookbook/filtered-view/example-3.png b/docs/cookbook/filtered-view/example-3.png deleted file mode 100644 index f0f1481..0000000 Binary files a/docs/cookbook/filtered-view/example-3.png and /dev/null differ diff --git a/docs/cookbook/groups/README.md b/docs/cookbook/groups/README.md deleted file mode 100644 index af2e65a..0000000 --- a/docs/cookbook/groups/README.md +++ /dev/null @@ -1,168 +0,0 @@ -# Groups - -The `group` keyword provides a way to define a named grouping of elements, which will be rendered as a boundary around those elements. -See [DSL language reference - group](../../language-reference.md#group) for more details. - -## Example - -Here is an example of a system landscape diagram that uses groups to represent organisational boundaries. - -``` -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - } - -} -``` - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/groups/example-1.dsl) - -## Styling all groups - -By default, groups are shown as dashed boundaries with a light grey colour. -This can be customised via an element style, as described at [Structurizr - Notation](https://structurizr.com/help/notation). - -To change the style for all groups, add an element style for the `Group` tag. - -``` -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group" { - color #ff0000 - } - } - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/groups/example-2.dsl) - -## Styling individual groups - -To change the style of an individual group, add an element style for the `Group:XXX` tag, where `XXX` is the name of the group. - -``` -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group:Company 1" { - color #ff0000 - } - } - } - -} -``` - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/groups/example-3.dsl) - -## Nested groups - -Groups can also be nested. Element groups are defined as a single string property on the element named `group`, -and defining nested groups requires a separator to be defined that will be used to split this single string into a set of hierarchical/nested groups. -To do this, add a model property named `structurizr.groupSeparator` that defines a separator to use, and be sure to not use this separator in your group names. -Styling nested groups requires using the full hierarchical group name when defining the element style. - -``` -workspace { - - model { - properties { - "structurizr.groupSeparator" "/" - } - - group "Company 1" { - group "Department 1" { - a = softwareSystem "A" - } - - group "Department 2" { - b = softwareSystem "B" - } - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group:Company 1/Department 1" { - color #ff0000 - } - element "Group:Company 1/Department 2" { - color #0000ff - } - } - } - -} -``` - -[![](example-4.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/groups/example-4.dsl) - -## Notes - -Please note that element styles are designed to work with the Structurizr cloud service/on-premises installation/Lite, and may not be fully supported by the PlantUML, Mermaid, etc export formats. -Only the `color` and `icon` properties can be customised for groups. - -- [Structurizr - Notation](https://structurizr.com/help/notation) \ No newline at end of file diff --git a/docs/cookbook/groups/example-1.dsl b/docs/cookbook/groups/example-1.dsl deleted file mode 100644 index 58eefe3..0000000 --- a/docs/cookbook/groups/example-1.dsl +++ /dev/null @@ -1,22 +0,0 @@ -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/groups/example-1.png b/docs/cookbook/groups/example-1.png deleted file mode 100644 index 3e5844e..0000000 Binary files a/docs/cookbook/groups/example-1.png and /dev/null differ diff --git a/docs/cookbook/groups/example-2.dsl b/docs/cookbook/groups/example-2.dsl deleted file mode 100644 index 398af3b..0000000 --- a/docs/cookbook/groups/example-2.dsl +++ /dev/null @@ -1,28 +0,0 @@ -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group" { - color #ff0000 - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/groups/example-2.png b/docs/cookbook/groups/example-2.png deleted file mode 100644 index 458eca8..0000000 Binary files a/docs/cookbook/groups/example-2.png and /dev/null differ diff --git a/docs/cookbook/groups/example-3.dsl b/docs/cookbook/groups/example-3.dsl deleted file mode 100644 index 96e94df..0000000 --- a/docs/cookbook/groups/example-3.dsl +++ /dev/null @@ -1,28 +0,0 @@ -workspace { - - model { - group "Company 1" { - a = softwareSystem "A" - } - - group "Company 2" { - b = softwareSystem "B" - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group:Company 1" { - color #ff0000 - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/groups/example-3.png b/docs/cookbook/groups/example-3.png deleted file mode 100644 index a04b7ed..0000000 Binary files a/docs/cookbook/groups/example-3.png and /dev/null differ diff --git a/docs/cookbook/groups/example-4.dsl b/docs/cookbook/groups/example-4.dsl deleted file mode 100644 index cc23f6a..0000000 --- a/docs/cookbook/groups/example-4.dsl +++ /dev/null @@ -1,37 +0,0 @@ -workspace { - - model { - properties { - "structurizr.groupSeparator" "/" - } - - group "Company 1" { - group "Department 1" { - a = softwareSystem "A" - } - - group "Department 2" { - b = softwareSystem "B" - } - } - - a -> b - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - element "Group:Company 1/Department 1" { - color #ff0000 - } - element "Group:Company 1/Department 2" { - color #0000ff - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/groups/example-4.png b/docs/cookbook/groups/example-4.png deleted file mode 100644 index a2e93e1..0000000 Binary files a/docs/cookbook/groups/example-4.png and /dev/null differ diff --git a/docs/cookbook/image-view/README.md b/docs/cookbook/image-view/README.md deleted file mode 100644 index 858965b..0000000 --- a/docs/cookbook/image-view/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Image view - -An [image view](https://structurizr.com/help/image-views) represents an image that has been rendered outside of Structurizr, for inclusion in a Structurizr workspace. -Image views can be created from an arbitrary PNG/SVG file, or a PlantUML/Mermaid/Kroki diagram. -An example use case for an image view is to provide a "level 4" zoom-in for a component on a component diagram. - -``` -workspace { - - model { - softwareSystem "Software System" { - container = container "Container" { - component1 = component "Component 1" - } - } - } - - views { - properties { - "mermaid.url" "https://mermaid.ink" - "mermaid.format" "svg" - } - - component container { - include * - autoLayout lr - } - - image component1 { - mermaid https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/image-view/component1.mmd - title "Class diagram for Component1" - } - } - -} -``` - -This DSL defines an image view for the "Component 1" component, based upon a Mermaid class diagram. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/image-view/example-1.dsl) - -## Links - -- [Structurizr - Help - Image views](https://structurizr.com/help/image-views) -- [DSL language reference - image view](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#image-view) \ No newline at end of file diff --git a/docs/cookbook/image-view/component1.mmd b/docs/cookbook/image-view/component1.mmd deleted file mode 100644 index fae4384..0000000 --- a/docs/cookbook/image-view/component1.mmd +++ /dev/null @@ -1,4 +0,0 @@ -classDiagram - direction RL - Component1 <|.. Component1Impl : implements - <> Component1 \ No newline at end of file diff --git a/docs/cookbook/image-view/example-1.dsl b/docs/cookbook/image-view/example-1.dsl deleted file mode 100644 index e08c7c3..0000000 --- a/docs/cookbook/image-view/example-1.dsl +++ /dev/null @@ -1,28 +0,0 @@ -workspace { - - model { - softwareSystem "Software System" { - container = container "Container" { - component1 = component "Component 1" - } - } - } - - views { - properties { - "mermaid.url" "https://mermaid.ink" - "mermaid.format" "svg" - } - - component container { - include * - autoLayout lr - } - - image component1 { - mermaid https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/image-view/component1.mmd - title "Class diagram for Component1" - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/image-view/example-1.png b/docs/cookbook/image-view/example-1.png deleted file mode 100644 index fa40204..0000000 Binary files a/docs/cookbook/image-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/implied-relationships/README.md b/docs/cookbook/implied-relationships/README.md deleted file mode 100644 index 94f06cf..0000000 --- a/docs/cookbook/implied-relationships/README.md +++ /dev/null @@ -1,126 +0,0 @@ -# Implied relationships - -By default, the Structurizr DSL will create "implied relationships" automatically. For example, consider the following DSL, which defines a relationship between a person and a container. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} -``` - -Although the DSL does not define an explicit relationship between the person and the software system, this relationship is implied because of the relationship between the person and the container that resides inside the software system. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/implied-relationships/example-1.dsl) - -## Disabling implied relationships - -This functionality can be disabled using the `!impliedRelationships` keyword. For example: - -``` -workspace { - - !impliedRelationships false - - model { - - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses" - } - - views { - systemContext s { - include u s - autoLayout - } - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/implied-relationships/example-2.dsl) - -With the implied relationships functionality disabled, you will need to explicitly define every relationship that you want to see on your diagrams. - -## Multiple implied relationships - -The Structurizr DSL uses the [CreateImpliedRelationshipsUnlessAnyRelationshipExistsStrategy](https://github.com/structurizr/java/blob/master/docs/implied-relationships.md#createimpliedrelationshipsunlessanyrelationshipexistsstrategy) from the Java client library when creating implied relationships, which prevents multiple implied relationships from being created. For example, the following DSL will only create a single implied relationship between the person and the software system (the first that is defined in the DSL). - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses 1" - u -> webapp "Uses 2" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} -``` - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/implied-relationships/example-3.dsl) - -To show both relationships, you will need to explitly define them, as follows: - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> s "Uses 1" - u -> s "Uses 2" - u -> webapp "Uses 1" - u -> webapp "Uses 2" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} -``` - -[![](example-4.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/implied-relationships/example-4.dsl) - -A better approach is to collapse multiple relationships into a single description, modelling the summary of all relationships rather than each individual relationship. This leads to less cluttered diagrams. See [Modelling multiple relationships](https://dev.to/simonbrown/modelling-multiple-relationships-51bf) for more on this topic. - -## Links - -- [DSL language reference - !impliedRelationships](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#impliedRelationships) \ No newline at end of file diff --git a/docs/cookbook/implied-relationships/example-1.dsl b/docs/cookbook/implied-relationships/example-1.dsl deleted file mode 100644 index 892ec03..0000000 --- a/docs/cookbook/implied-relationships/example-1.dsl +++ /dev/null @@ -1,19 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/implied-relationships/example-1.png b/docs/cookbook/implied-relationships/example-1.png deleted file mode 100644 index d1cc881..0000000 Binary files a/docs/cookbook/implied-relationships/example-1.png and /dev/null differ diff --git a/docs/cookbook/implied-relationships/example-2.dsl b/docs/cookbook/implied-relationships/example-2.dsl deleted file mode 100644 index be390aa..0000000 --- a/docs/cookbook/implied-relationships/example-2.dsl +++ /dev/null @@ -1,22 +0,0 @@ -workspace { - - !impliedRelationships false - - model { - - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses" - } - - views { - systemContext s { - include u s - autoLayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/implied-relationships/example-2.png b/docs/cookbook/implied-relationships/example-2.png deleted file mode 100644 index b0ef789..0000000 Binary files a/docs/cookbook/implied-relationships/example-2.png and /dev/null differ diff --git a/docs/cookbook/implied-relationships/example-3.dsl b/docs/cookbook/implied-relationships/example-3.dsl deleted file mode 100644 index 3ffe407..0000000 --- a/docs/cookbook/implied-relationships/example-3.dsl +++ /dev/null @@ -1,20 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> webapp "Uses 1" - u -> webapp "Uses 2" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/implied-relationships/example-3.png b/docs/cookbook/implied-relationships/example-3.png deleted file mode 100644 index fd1f271..0000000 Binary files a/docs/cookbook/implied-relationships/example-3.png and /dev/null differ diff --git a/docs/cookbook/implied-relationships/example-4.dsl b/docs/cookbook/implied-relationships/example-4.dsl deleted file mode 100644 index 761bc8f..0000000 --- a/docs/cookbook/implied-relationships/example-4.dsl +++ /dev/null @@ -1,22 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" { - webapp = container "Web Application" - } - - u -> s "Uses 1" - u -> s "Uses 2" - u -> webapp "Uses 1" - u -> webapp "Uses 2" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/implied-relationships/example-4.png b/docs/cookbook/implied-relationships/example-4.png deleted file mode 100644 index 8c91c4b..0000000 Binary files a/docs/cookbook/implied-relationships/example-4.png and /dev/null differ diff --git a/docs/cookbook/introduction/1.png b/docs/cookbook/introduction/1.png deleted file mode 100644 index d06a506..0000000 Binary files a/docs/cookbook/introduction/1.png and /dev/null differ diff --git a/docs/cookbook/introduction/2.png b/docs/cookbook/introduction/2.png deleted file mode 100644 index d1e5f64..0000000 Binary files a/docs/cookbook/introduction/2.png and /dev/null differ diff --git a/docs/cookbook/introduction/3.png b/docs/cookbook/introduction/3.png deleted file mode 100644 index 725c55f..0000000 Binary files a/docs/cookbook/introduction/3.png and /dev/null differ diff --git a/docs/cookbook/introduction/4.png b/docs/cookbook/introduction/4.png deleted file mode 100644 index 9d33d85..0000000 Binary files a/docs/cookbook/introduction/4.png and /dev/null differ diff --git a/docs/cookbook/introduction/README.md b/docs/cookbook/introduction/README.md deleted file mode 100644 index 2c577b8..0000000 --- a/docs/cookbook/introduction/README.md +++ /dev/null @@ -1,73 +0,0 @@ -# Introduction - -Creating software architecture diagrams from text is becoming more popular. Text is easy to work with, and it's version controllable, so it can be stored alongside your source code. Tools like [PlantUML](https://plantuml.com), [Mermaid](https://mermaid-js.github.io/mermaid/#/), and [WebSequenceDiagrams](https://www.websequencediagrams.com) have auto-layout algorithms that allow us to focus on content too. - -In conjunction with the [C4 model](https://c4model.com), it's relatively straightforward to create a collection of diagrams to describe the project/product you're working on, at different levels of abstraction. For example, here's a [System Context diagram](https://c4model.com/#SystemContextDiagram) to describe a pet clinic information management system. - -![An example System Context diagram](1.png) - -And here's a [Container diagram](https://c4model.com/#ContainerDiagram) showing the internals of the software system. - -![An example Container diagram](2.png) - -## But wait! - -Did you spot the two errors in the Container diagram? Let's look at the diagrams next to each other. - -![](3.png) - -- "Clinic Employee" has changed to "Clinic Staff". -- The arrow style has changed from dashed to solid. - -Granted these are only minor differences, but the problem here is one of consistency. If you're defining two diagrams in two separate text files, it's easy to make mistakes. Also, perhaps we wanted to change the name of the user from "Clinic Employee" to "Clinic Staff", but we forgot to change both files or regenerate them both. Some of these problems can be partially solved with the global search and replace tooling we have at our disposal as software developers. And some problems can be solved by integrating the diagram generation process into a CI/CD pipeline. But there's a better way. - -## Make models, not diagrams - -What we're missing here is a single definition of the elements and relationships across all of our diagrams. When writing code, we often talk about DRY ([Don't repeat yourself](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)), where we try to avoid unnecessary duplication through copy-pasting code. That's exactly how many people create their diagrams though, by copy-pasting diagram definition fragments. PlantUML does support the concept of an [!include directive](https://mrhaki.blogspot.com/2016/12/plantuml-pleasantness-include-partial.html) to include fragments, but this can become complicated. - -What we really want to do is create a model of our software architecture, and then visualise it from different angles. The [Structurizr DSL](https://github.com/structurizr/dsl) is an open source project that lets you do just this. Instead of writing two separate PlantUML files, we can define everything in a single file as follows. - -``` -workspace { - - model { - clinicEmployee = person "Clinic Employee" - springPetClinic = softwareSystem "Spring PetClinic"{ - webApplication = container "Web Application" - database = container "Database" - } - - clinicEmployee -> webApplication "Uses" - webApplication -> database "Reads from and writes to" - } - - views { - systemContext springPetClinic { - include * - autolayout - } - - container springPetClinic { - include * - autolayout - } - } - -} -``` - -[View this example online](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/introduction/example.dsl) - -This text defines a model containing: a user, a software system, two containers, and the relationships between everything. It also then defines two views of this model: one System Context view, and one Container view. - -The DSL is a way to define software architecture models and views, but we still need a way to visualise that, and ultimately get some diagrams. We can do this with the [Structurizr CLI](https://github.com/structurizr/cli), another open source project that has a number of features. - -```text -./structurizr.sh export -workspace example.dsl -format plantuml -``` - -Running the Structurizr CLI in this way will create two `.puml` files, which we can then render with PlantUML in the normal way. - - ![Example System Context and Container diagrams](4.png) - -Because both diagrams are created from the same model, they remain in sync, both from a content and a presentation perspective. Changes can now be made to the original DSL source file, and the diagrams regenerated. \ No newline at end of file diff --git a/docs/cookbook/introduction/example.dsl b/docs/cookbook/introduction/example.dsl deleted file mode 100644 index 5810f14..0000000 --- a/docs/cookbook/introduction/example.dsl +++ /dev/null @@ -1,26 +0,0 @@ -workspace { - - model { - clinicEmployee = person "Clinic Employee" - springPetClinic = softwareSystem "Spring PetClinic"{ - webApplication = container "Web Application" - database = container "Database" - } - - clinicEmployee -> webApplication "Uses" - webApplication -> database "Reads from and writes to" - } - - views { - systemContext springPetClinic { - include * - autolayout - } - - container springPetClinic { - include * - autolayout - } - } - -} diff --git a/docs/cookbook/perspectives/README.md b/docs/cookbook/perspectives/README.md deleted file mode 100644 index b8d7b7a..0000000 --- a/docs/cookbook/perspectives/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# Perspectives - -Structurizr supports the concept of "perspectives" from [viewpoints and perspectives](https://www.viewpoints-and-perspectives.info/home/perspectives/), where you want to look at a diagram with a view to answering a particular question. -Perhaps you have a system landscape diagram showing software systems, and you'd like to see the ownership of each software system. -Or perhaps you have a container diagram, and you'd like to see details of how each container satisifies the security requirements. - -Perspectives can be added to any model element or relationship; for example: - -``` -workspace { - - model { - a = softwareSystem "A" { - perspectives { - "Ownership" "Team 1" - } - } - - b = softwareSystem "B" { - perspectives { - "Ownership" "Team 2" - } - } - } - - views { - systemLandscape { - include * - autoLayout - } - } - -} -``` - -This DSL defines an "Ownership" perspective for each software system, which can be viewed by following the instructions at [Structurizr - Help - Perspectives](https://structurizr.com/help/perspectives). - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/perspectives/example-1.dsl&perspective=Ownership) - -## Links - -- [DSL language reference - perspectives](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#perspectives) \ No newline at end of file diff --git a/docs/cookbook/perspectives/example-1.dsl b/docs/cookbook/perspectives/example-1.dsl deleted file mode 100644 index 64625b2..0000000 --- a/docs/cookbook/perspectives/example-1.dsl +++ /dev/null @@ -1,24 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" { - perspectives { - "Ownership" "Team 1" - } - } - - b = softwareSystem "B" { - perspectives { - "Ownership" "Team 2" - } - } - } - - views { - systemLandscape { - include * - autoLayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/perspectives/example-1.png b/docs/cookbook/perspectives/example-1.png deleted file mode 100644 index 0331299..0000000 Binary files a/docs/cookbook/perspectives/example-1.png and /dev/null differ diff --git a/docs/cookbook/relationship-styles/README.md b/docs/cookbook/relationship-styles/README.md deleted file mode 100644 index 92488bf..0000000 --- a/docs/cookbook/relationship-styles/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# Relationship styles - -By default all relationships are styled as dashed grey lines. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/relationship-styles/example-1.dsl) - -## Styling all relationships - -To change the style for all relationships, add a relationship style for the `Relationship` tag. - -``` -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - relationship "Relationship" { - color #ff0000 - dashed false - } - } - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/relationship-styles/example-2.dsl) - -## Styling individual relationships - -To change the style of an individual relationship: - -1. Tag the relationship. -2. Add a relationship style for that tag. - -``` -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c { - tags "Tag 1" - } - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - relationship "Tag 1" { - color #ff0000 - dashed false - } - } - } - -} -``` - -[![](example-3.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/relationship-styles/example-3.dsl) - -## Notes - -Please note that relationship styles are designed to work with the Structurizr cloud service/on-premises installation, and may not be fully supported by the PlantUML, Mermaid, etc export formats. - -- [DSL language reference - styles - relationship](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#relationship-style) \ No newline at end of file diff --git a/docs/cookbook/relationship-styles/example-1.dsl b/docs/cookbook/relationship-styles/example-1.dsl deleted file mode 100644 index 42e1361..0000000 --- a/docs/cookbook/relationship-styles/example-1.dsl +++ /dev/null @@ -1,19 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/relationship-styles/example-1.png b/docs/cookbook/relationship-styles/example-1.png deleted file mode 100644 index abde92f..0000000 Binary files a/docs/cookbook/relationship-styles/example-1.png and /dev/null differ diff --git a/docs/cookbook/relationship-styles/example-2.dsl b/docs/cookbook/relationship-styles/example-2.dsl deleted file mode 100644 index 40a9865..0000000 --- a/docs/cookbook/relationship-styles/example-2.dsl +++ /dev/null @@ -1,26 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - relationship "Relationship" { - color #ff0000 - dashed false - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/relationship-styles/example-2.png b/docs/cookbook/relationship-styles/example-2.png deleted file mode 100644 index 041938f..0000000 Binary files a/docs/cookbook/relationship-styles/example-2.png and /dev/null differ diff --git a/docs/cookbook/relationship-styles/example-3.dsl b/docs/cookbook/relationship-styles/example-3.dsl deleted file mode 100644 index 2898eef..0000000 --- a/docs/cookbook/relationship-styles/example-3.dsl +++ /dev/null @@ -1,28 +0,0 @@ -workspace { - - model { - a = softwareSystem "A" - b = softwareSystem "B" - c = softwareSystem "C" - - a -> b - b -> c { - tags "Tag 1" - } - } - - views { - systemLandscape { - include * - autolayout lr - } - - styles { - relationship "Tag 1" { - color #ff0000 - dashed false - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/relationship-styles/example-3.png b/docs/cookbook/relationship-styles/example-3.png deleted file mode 100644 index b7e461e..0000000 Binary files a/docs/cookbook/relationship-styles/example-3.png and /dev/null differ diff --git a/docs/cookbook/scripts/README.md b/docs/cookbook/scripts/README.md deleted file mode 100644 index cda6f90..0000000 --- a/docs/cookbook/scripts/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Scripts - -The `!script` keyword provides a way to run scripts written in Groovy, Kotlin, Ruby, and JavaScript. -This gives you access to the underlying [Workspace](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/Workspace.java) via a variable named `workspace`, -for when you need to do something not supported by the DSL. -Other variables (`element`, `relationship`, `view`) are available depending on where the script is defined; see the [DSL language reference - Scripts](../../language-reference.md#scripts) for more details. -Here are some useful scripts. - -#### Create the default views, without automatic layout - -``` -!script groovy { - workspace.views.createDefaultViews() - workspace.views.views.findAll { it instanceof com.structurizr.view.ModelView }.each { it.disableAutomaticLayout() } -} -``` - -#### Programmatically add elements to a view - -``` -workspace { - - model { - group "Group 1" { - a = softwareSystem "A" { - tags "Tag 1" - } - b = softwareSystem "B" { - tags "Tag 2" - } - } - group "Group 2" { - c = softwareSystem "C" { - tags "Tag 1" - } - d = softwareSystem "D" { - tags "Tag 2" - } - } - } - - views { - systemLandscape "key" { - !script groovy { - workspace.model.softwareSystems.findAll { it.group == "Group 1" && it.hasTag("Tag 1") }.each{ view.add(it); }; - } - - autolayout - } - } - -} -``` - -#### Run Graphviz locally - -``` -!script groovy { - new com.structurizr.graphviz.GraphvizAutomaticLayout().apply(workspace); -} -``` - -(this requires Graphviz to be installed locally) - -## Links - -- [DSL language reference - Scripts](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#scripts) -- [Structurizr for Java source code](https://github.com/structurizr/java/tree/master/structurizr-core/src/com/structurizr) diff --git a/docs/cookbook/shared-components/README.md b/docs/cookbook/shared-components/README.md deleted file mode 100644 index c11895d..0000000 --- a/docs/cookbook/shared-components/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# Shared components - -Diagramming components that are shared between containers is relatively straightforward with a combination of -`!identifiers hierarchical` and `!include`. - -First, define your shared components in a DSL fragment, [for example](shared-library.dsl): - -``` -loggingComponent = component "Logging Component" { - technology "Java" - description "A wrapper around the log4j framework" - tags "Shared Component" -} -``` - -Next, define your containers, and include the shared components using the `!include` statement: - -``` -workspace { - - !identifiers hierarchical - - model { - s = softwareSystem "Software System" { - app1 = container "Application 1" { - group "shared-library.jar" { - !include shared-library.dsl - } - - c = component "Component" { - -> loggingComponent "Writes logs using" - } - } - - app2 = container "Application 2" { - group "shared-library.jar" { - !include shared-library.dsl - } - - c = component "Component" { - -> loggingComponent "Writes logs using" - } - } - } - } - - views { - component s.app1 { - include * - autolayout lr - } - - component s.app2 { - include * - autoLayout lr - } - - styles { - ... - } - } - -} -``` - -The use of `!identifiers hierarchical` prevents the shared component identifiers from clashing, -and you can reference the shared components via `s.app1.loggingComponent` and `s.app2.loggingComponent` respectively if required. - -This DSL also uses a group and differing notation to highlight the shared components. -The `group` statement has been included in the main DSL file in this example, but it could be moved to the `shared-library.dsl` file if desired. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/shared-components/example-1.dsl) - -## Links - -- [The C4 model for visualising software architecture](https://leanpub.com/visualising-software-architecture) (this shows more strategies and examples for diagramming shared components) \ No newline at end of file diff --git a/docs/cookbook/shared-components/example-1.dsl b/docs/cookbook/shared-components/example-1.dsl deleted file mode 100644 index 969405b..0000000 --- a/docs/cookbook/shared-components/example-1.dsl +++ /dev/null @@ -1,56 +0,0 @@ -workspace { - - !identifiers hierarchical - - model { - s = softwareSystem "Software System" { - app1 = container "Application 1" { - group "shared-library.jar" { - !include https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/shared-components/shared-library.dsl - } - - c = component "Component" { - -> loggingComponent "Writes logs using" - } - } - - app2 = container "Application 2" { - group "shared-library.jar" { - !include https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/shared-components/shared-library.dsl - } - - c = component "Component" { - -> loggingComponent "Writes logs using" - } - } - } - } - - views { - component s.app1 { - include * - autolayout lr - } - - component s.app2 { - include * - autoLayout lr - } - - styles { - element "Container" { - background #777777 - } - element "Group" { - colour #777777 - } - element "Component" { - background #dddddd - } - element "Shared Component" { - background #f9f9f9 - } - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/shared-components/example-1.png b/docs/cookbook/shared-components/example-1.png deleted file mode 100644 index 80bdb01..0000000 Binary files a/docs/cookbook/shared-components/example-1.png and /dev/null differ diff --git a/docs/cookbook/shared-components/shared-library.dsl b/docs/cookbook/shared-components/shared-library.dsl deleted file mode 100644 index 85c413a..0000000 --- a/docs/cookbook/shared-components/shared-library.dsl +++ /dev/null @@ -1,5 +0,0 @@ -loggingComponent = component "Logging Component" { - technology "Java" - description "A wrapper around the log4j framework" - tags "Shared Component" -} \ No newline at end of file diff --git a/docs/cookbook/system-context-view/README.md b/docs/cookbook/system-context-view/README.md deleted file mode 100644 index a6b98a1..0000000 --- a/docs/cookbook/system-context-view/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# System Context view - -A [system context view](https://c4model.com/#SystemContextDiagram) is a good starting point for diagramming and documenting a software system, allowing you to step back and see the big picture. It shows the software system in the centre, surrounded by its users and the other systems that it interacts with. - -``` -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" - - u -> s "Uses" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} -``` - -This DSL defines a system context view for the software system `s`, and `include *` includes all model elements that have a direct relationship with it. - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/system-context-view/example-1.dsl) - -System context views can be rendered using the Structurizr cloud service/on-premises installation or exported to a number of other formats via the [Structurizr CLI export command](https://github.com/structurizr/cli/blob/master/docs/export.md). - -## Links - -- [DSL language reference - systemContext](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#systemContext-view) \ No newline at end of file diff --git a/docs/cookbook/system-context-view/example-1.dsl b/docs/cookbook/system-context-view/example-1.dsl deleted file mode 100644 index 316c777..0000000 --- a/docs/cookbook/system-context-view/example-1.dsl +++ /dev/null @@ -1,17 +0,0 @@ -workspace { - - model { - u = person "User" - s = softwareSystem "Software System" - - u -> s "Uses" - } - - views { - systemContext s { - include * - autoLayout lr - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/system-context-view/example-1.png b/docs/cookbook/system-context-view/example-1.png deleted file mode 100644 index 6ddc89f..0000000 Binary files a/docs/cookbook/system-context-view/example-1.png and /dev/null differ diff --git a/docs/cookbook/themes/README.md b/docs/cookbook/themes/README.md deleted file mode 100644 index 67b1e4e..0000000 --- a/docs/cookbook/themes/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# Themes - -Some pre-built themes are available to help you diagram deployment architectures that make use of popular cloud providers such as Amazon Web Services, Microsoft Azure, Google Cloud Platform, etc. Links to these themes can be found at [Structurizr - Help - Themes](https://structurizr.com/help/themes). You can also create your own themes. - -## What is a theme? - -A theme is a JSON file consisting of one or more element/relationship styles that are defined for specific tags. Themes need to be hosted at a publicly accessible URL, and hosted over HTTPS if you're using the Structurizr cloud service. For example, a pre-built Microsoft Azure theme can be found at the following URL: - -- [https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json](https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json) - -You can use the Structurizr theme browser to view the styles that are defined in the theme, with the following URL: - -- [https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json](https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json) - -## Using a theme - -The ```theme``` or ```themes``` keywords can be used to include one or more themes in your workspace. You will also need to add the appropriate tags to your model elements/relationships. - -``` -workspace { - - model { - softwareSystem "Authentication Service" { - tags "Microsoft Azure - Azure Active Directory" - } - } - - views { - systemLandscape { - include * - autoLayout lr - } - - theme https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json - } - -} -``` - -[![](example-1.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/themes/example-1.dsl) - -For further customisation, themes can be used in conjunction with element/relationship styles that are defined in the workspace. - -``` -workspace { - - model { - softwareSystem "Authentication Service" { - tags "Microsoft Azure - Azure Active Directory" - } - } - - views { - systemLandscape { - include * - autoLayout lr - } - - styles { - element "Software System" { - background #ffffff - shape RoundedBox - } - } - - theme https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json - } - -} -``` - -[![](example-2.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/themes/example-2.dsl) - -## Notes - -Please note that themes are designed to work with the Structurizr cloud service/on-premises installation/Lite, and may not be fully supported by the PlantUML, Mermaid, etc export formats. - -- [DSL language reference - theme](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#theme) -- [DSL language reference - themes](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#themes) \ No newline at end of file diff --git a/docs/cookbook/themes/example-1.dsl b/docs/cookbook/themes/example-1.dsl deleted file mode 100644 index 323b5d9..0000000 --- a/docs/cookbook/themes/example-1.dsl +++ /dev/null @@ -1,18 +0,0 @@ -workspace { - - model { - softwareSystem "Authentication Service" { - tags "Microsoft Azure - Azure Active Directory" - } - } - - views { - systemLandscape { - include * - autoLayout lr - } - - theme https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json - } - -} \ No newline at end of file diff --git a/docs/cookbook/themes/example-1.png b/docs/cookbook/themes/example-1.png deleted file mode 100644 index 9acc909..0000000 Binary files a/docs/cookbook/themes/example-1.png and /dev/null differ diff --git a/docs/cookbook/themes/example-2.dsl b/docs/cookbook/themes/example-2.dsl deleted file mode 100644 index 268a344..0000000 --- a/docs/cookbook/themes/example-2.dsl +++ /dev/null @@ -1,25 +0,0 @@ -workspace { - - model { - softwareSystem "Authentication Service" { - tags "Microsoft Azure - Azure Active Directory" - } - } - - views { - systemLandscape { - include * - autoLayout lr - } - - styles { - element "Software System" { - background #ffffff - shape RoundedBox - } - } - - theme https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json - } - -} \ No newline at end of file diff --git a/docs/cookbook/themes/example-2.png b/docs/cookbook/themes/example-2.png deleted file mode 100644 index 9f9c3cb..0000000 Binary files a/docs/cookbook/themes/example-2.png and /dev/null differ diff --git a/docs/cookbook/workspace-extension/A-Containers.png b/docs/cookbook/workspace-extension/A-Containers.png deleted file mode 100644 index 07e5f2a..0000000 Binary files a/docs/cookbook/workspace-extension/A-Containers.png and /dev/null differ diff --git a/docs/cookbook/workspace-extension/A-SystemContext.png b/docs/cookbook/workspace-extension/A-SystemContext.png deleted file mode 100644 index 72f06ca..0000000 Binary files a/docs/cookbook/workspace-extension/A-SystemContext.png and /dev/null differ diff --git a/docs/cookbook/workspace-extension/README.md b/docs/cookbook/workspace-extension/README.md deleted file mode 100644 index 50d09fe..0000000 --- a/docs/cookbook/workspace-extension/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Workspace extension - -The Structurizr DSL provides a way to extend an existing workspace, enabling you to reuse common elements/relationships across multiple workspaces. To use this feature, define your workspace as normal. For example: - -``` -workspace { - - !identifiers hierarchical - - model { - a = softwareSystem "A" - b = softwareSystem "B" - - a -> b "Gets data X from" - } - -} -``` - -Next, define your child workspace, using the `extends` keyword to specify the workspace that should be extended. For example: - -``` -workspace extends https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/workspace-extension/system-landscape.dsl { - - model { - !ref a { - webapp = container "Web Application" - database = container "Database" - - webapp -> b "Gets data X from" - webapp -> database "Reads from and writes to" - } - } - - views { - systemContext a "A-SystemContext" { - include * - autolayout lr - } - - container a "A-Containers" { - include * - autolayout - } - } - -} -``` - -In this example we're extending a workspace that's accessible via a public URL, but you can also specify the name of a local file. We can use the `!ref` keyword to reference and extend the existing software system named "A", which is identified in the parent workspace as `a`. Since `b` is already defined in the parent workspace, we can reference it from the child workspace as if it was defined locally. - -This will create a system context diagram: - -[![](A-SystemContext.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/workspace-extension/a.dsl&view=A-SystemContext) - -And a container diagram: - -[![](A-Containers.png)](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/workspace-extension/a.dsl&view=A-Containers) - -## Links - -- [DSL language reference - workspace](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#workspace) -- [DSL language reference - ref](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#ref) \ No newline at end of file diff --git a/docs/cookbook/workspace-extension/a.dsl b/docs/cookbook/workspace-extension/a.dsl deleted file mode 100644 index e0bec62..0000000 --- a/docs/cookbook/workspace-extension/a.dsl +++ /dev/null @@ -1,25 +0,0 @@ -workspace extends https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/workspace-extension/system-landscape.dsl { - - model { - !ref a { - webapp = container "Web Application" - database = container "Database" - - webapp -> b "Gets data X from" - webapp -> database "Reads from and writes to" - } - } - - views { - systemContext a "A-SystemContext" { - include * - autolayout lr - } - - container a "A-Containers" { - include * - autolayout - } - } - -} \ No newline at end of file diff --git a/docs/cookbook/workspace-extension/system-landscape.dsl b/docs/cookbook/workspace-extension/system-landscape.dsl deleted file mode 100644 index 50ef858..0000000 --- a/docs/cookbook/workspace-extension/system-landscape.dsl +++ /dev/null @@ -1,12 +0,0 @@ -workspace { - - !identifiers hierarchical - - model { - a = softwareSystem "A" - b = softwareSystem "B" - - a -> b "Gets data X from" - } - -} \ No newline at end of file diff --git a/docs/cookbook/workspace/README.md b/docs/cookbook/workspace/README.md deleted file mode 100644 index f3334f4..0000000 --- a/docs/cookbook/workspace/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Workspace - -In Structurizr terminology, a "workspace" is a wrapper for a software architecture model (elements and relationships) and views. - -``` -workspace "Name" "Description" { - - model { - } - - views { - } - -} -``` - -A workspace can be given a name and description, although these are only used by the [Structurizr cloud service and on-premises installation](https://structurizr.com) - you don't need to specify a name/description if you're exporting views to one of the export formats (PlantUML, Mermaid, etc). - -## Links - -- [DSL language reference - workspace](https://github.com/structurizr/dsl/blob/master/docs/language-reference.md#workspace) -- [Example](http://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/dsl/master/docs/cookbook/workspace/example-1.dsl) diff --git a/docs/cookbook/workspace/example-1.dsl b/docs/cookbook/workspace/example-1.dsl deleted file mode 100644 index 5e6388a..0000000 --- a/docs/cookbook/workspace/example-1.dsl +++ /dev/null @@ -1,9 +0,0 @@ -workspace "Name" "Description" { - - model { - } - - views { - } - -} diff --git a/docs/images/quick-example.png b/docs/images/quick-example.png deleted file mode 100644 index 07769a5..0000000 Binary files a/docs/images/quick-example.png and /dev/null differ diff --git a/docs/images/structurizr-banner.png b/docs/images/structurizr-banner.png deleted file mode 100644 index a9a0b0a..0000000 Binary files a/docs/images/structurizr-banner.png and /dev/null differ diff --git a/docs/language-reference.md b/docs/language-reference.md index 1f297a7..581cadd 100644 --- a/docs/language-reference.md +++ b/docs/language-reference.md @@ -1,1582 +1,3 @@ # Language reference -The Structurizr DSL provides a way to define a software architecture model -(based upon the [C4 model](https://c4model.com)) as text, using a domain specific language (DSL). -The DSL is rendering tool independent, and to render diagrams you will need to use one of the tools listed at -[Structurizr DSL - Rendering tools](https://github.com/structurizr/dsl#rendering-tools). - -Please see the [DSL cookbook](cookbook) for a tutorial guide to the Structurizr DSL. - -## Table of contents - -- [General rules](#general-rules) -- [Convention over configuration, useful defaults](#convention-over-configuration-useful-defaults) -- [String substitution](#string-substitution) -- [Comments](#comments) -- [Identifiers](#identifiers) -- [!include](#includes) -- [!constant](#constants) -- [Expressions](#expressions) -- [Plugins](#plugins) -- [Scripts](#scripts) -- [Grammar](#grammar) - - [workspace](#workspace) - - [!docs](#documentation) - - [!adrs](#architecture-decision-records-adrs) - - [!identifiers](#identifiers) - - [!impliedRelationships](#impliedRelationships) - - [model](#model) - - [enterprise](#enterprise) (deprecated) - - [group](#group) - - [person](#person) - - [softwareSystem](#softwareSystem) - - [container](#container) - - [component](#component) - - [deploymentEnvironment](#deploymentEnvironment) - - [deploymentGroup](#deploymentGroup) - - [deploymentNode](#deploymentNode) - - [infrastructureNode](#infrastructureNode) - - [softwareSystemInstance](#softwareSystemInstance) - - [containerInstance](#containerInstance) - - [element](#element) - - [-> (relationship)](#relationship) - - [!ref](#ref) - - [views](#views) - - [systemLandscape](#systemLandscape-view) - - [systemContext](#systemContext-view) - - [container](#container-view) - - [component](#component-view) - - [filtered](#filtered-view) - - [dynamic](#dynamic-view) - - [deployment](#deployment-view) - - [custom](#custom-view) - - [image](#image-view) - - [styles](#styles) - - [element](#element-style) - - [relationship](#relationship-style) - - [theme](#theme) - - [themes](#themes) - - [theme](#theme) - - [themes](#themes) - - [branding](#branding) - - [terminology](#terminology) - - [configuration](#configuration) - - [users](#users) - -## General rules - -- Line breaks are important; long lines can be split with `\` as the last character on the line. -- Lines are processed in order. -- Tokens must be separated by whitespace, but the quantity of whitespace/indentation isn't important. -- Keywords are case-insensitive (e.g. you can use `softwareSystem` or `softwaresystem`). -- Double quote characters (`"..."`) are optional when a property/expression contains no whitespace. -- Opening curly brace symbols (`{`) must be on the same line (i.e. the last token of the statement, not on a line of their own). -- Closing curly brace symbols (`}`) must be on a line of their own. -- Opening/closing braces are only required when adding child content. -- Use `""` as a placeholder for an earlier optional property that you'd like to skip. -- Tags are comma separated (e.g. `Tag 1,Tag 2,Tag 3`) - see [Structurizr - Notation](https://structurizr.com/help/notation) for details of how tags and styling works. -- The Structurizr CLI will provide some default views and styles when they are not specified in your DSL - see [Convention over configuration, useful defaults](#convention-over-configuration-useful-defaults) for details. - -In addition, workspaces are subject to the following rules: - -- Each view must have a unique "key" (this is generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__). -- Software and people names must be unique. -- Container names must be unique within the context of a software system. -- Component names must be unique within the context of a container. -- Deployment node names must be unique with their parent context. -- Infrastructure node names must be unique with their parent context. -- All relationships from a source element to a destination element must have a unique description. - -## Convention over configuration, useful defaults - -The DSL is designed to be as compact as possible. -When used in conjunction with [Structurizr Lite](https://structurizr.com/help/lite) -or the [Structurizr CLI](https://github.com/structurizr/cli), -the following DSL fragment will automatically: - -- Create the [implied relationship](docs/cookbook/implied-relationships) -between the ```user``` and ```softwareSystem``` elements. -- Create a default set of views (1 x System Landscape, 1 x System Context, 1 x Container - all with auto-layout enabled, see [ViewSet.createDefaultViews()](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/view/ViewSet.java)). -- Add some default element styles from a theme. - -``` -workspace { - - model { - user = person "User" - softwareSystem = softwareSystem "Software System" { - webapp = container "Web Application" - database = container "Database" - } - - user -> webapp "Uses" - webapp -> database "Reads from and writes to" - } - - views { - theme default - } - -} -``` - -## String substitution - -String substitution will take place on any text specified within a token using the `${NAME}` syntax, where `NAME` corresponds to a [constant](#constants) or an environment variable. -For example: - -``` -!constant ORGANISATION_NAME "Organisation" -!constant GROUP_NAME "Group" - -workspace { - - model { - group "${ORGANISATION_NAME} - ${GROUP_NAME}" { - user = person "User" - } - } - -} -``` - -If a named constant or environment variable cannot be found, the string will not be substituted. -Names may only contain the following characters: `a-zA-Z0-9-_.` - -## Comments - -Comments can be defined as follows: - -``` -/* - multi-line comment -*/ -``` - -``` -/* single-line comment */ -``` - -``` -# single line comment -``` - -``` -// single line comment -``` - -## Identifiers - -By default, all elements and relationships are anonymous, in that they can't be referenced from within the DSL. For example, the following statements will create a person and a software system, but neither can be referenced within the DSL. - -``` -person "User" -softwareSystem "Software System" -``` - -To create a relationship between the two elements, we need to be able to reference them. We can do this by defining an identifier, in the same way that you'd define a variable in many programming languages. - -``` -p = person "User" -ss = softwareSystem "Software System" -``` - -Now we can use these identifiers when creating relationships, specifying which elements should be included/excluded from views, etc. - -``` -p -> ss "Uses" -``` - -Relationships can also be assigned an identifier. - -``` -rel = p -> ss "Uses" -``` - -Identifiers are only needed where you plan to reference the element/relationship. The following characters may be used when defining an identifier: `a-zA-Z_0-9` - -### Identifier scope - -By default, all identifiers are treated as being globally scoped and `flat`, so the following will fail with an error message saying that the `api` identifier is already in use. - -``` -workspace { - - model { - softwareSystem1 = softwareSystem "Software System 1" { - api = container "API" - } - - softwareSystem2 = softwareSystem "Software System 2" { - api = container "API" - } - } -} -``` - -The `!identifiers` keyword allows you to specify that element identifiers should be treated as `hierarchical` (relationship identifiers are unaffected by this setting). For example: - -``` -workspace { - - !identifiers hierarchical - - model { - softwareSystem1 = softwareSystem "Software System 1" { - api = container "API" - } - - softwareSystem2 = softwareSystem "Software System 2" { - api = container "API" - } - } -} -``` - - Now the two API containers are referenceable via `softwareSystem1.api` and `softwareSystem2.api` respectively. - -### !impliedRelationships - -``` -!impliedRelationships -``` - -The `!impliedRelationships` keyword provides a way to enable or disable whether implied relationships are created. -A value of `false` disables implied relationship creation, while `true` creates implied relationships between all valid combinations of the parent elements, unless any relationship already exists between them -(see [Structurizr for Java - Implied relationships - CreateImpliedRelationshipsUnlessAnyRelationshipExistsStrategy](https://github.com/structurizr/java/blob/master/docs/implied-relationships.md#createimpliedrelationshipsunlessanyrelationshipexistsstrategy) for more details). - -## Includes - -The `!include` keyword can be used to include one or more files, to provide some degree of modularity, and to reuse definition fragments between workspaces. -The content of any included files is simply inlined into the parent document, in the order the files are discovered. - -``` -!include -``` - -- file: a single local file, specified by a relative path, located within the same directory as the parent file or a subdirectory of it -- directory: a local directory containing one or more DSL files, specified by a relative path, located within the same directory as the parent file or a subdirectory of it -- url: a HTTPS URL pointing to a single DSL file - -Some examples are: - -``` -!include people.dsl -!include model/people.dsl -!include model -!include https://example.com/model/people.dsl -``` - -## Constants - -The `!constant` keyword can be used to define a constant, which can be used with [string substitution](#string-substitution) - -``` -!constant -``` - -Constant names may only contain the following characters: `a-zA-Z0-9-_.` - -## Expressions - -The Structurizr DSL supports a number of expressions for use when including or excluding elements/relationships on views. - -- `->`: the specified element(s) plus afferent couplings -- `->`: the specified element(s) plus efferent couplings -- `->->`: the specified element(s) plus afferent and efferent couplings -- `element.type==`: elements of the specified type (Person|SoftwareSystem|Container|Component|DeploymentNode|InfrastructureNode|SoftwareSystemInstance|ContainerInstance|Custom) -- `element.parent==`: elements with the specified parent -- `element.tag==[,tag]`: all elements that have all of the specified tags -- `element.tag!=[,tag]`: all elements that do not have all of the specified tags -- `element==->`: the specified element plus afferent couplings -- `element==->`: the specified element plus efferent couplings -- `element==->->`: the specified element plus afferent and efferent couplings - -- `*->*`: all relationships -- `->*`: all relationships with the specified source element -- `*->`: all relationships with the specified destination element -- `relationship==*`: all relationships -- `relationship==*->*`: all relationships -- `relationship.tag==[,tag]`: all relationships that have all of the specified tags -- `relationship.tag!=[,tag]`: all relationships that do not have all of the specified tags -- `relationship.source==`: all relationships with the specified source element -- `relationship.destination==`: all relationships with the specified destination element -- `relationship==->*`: all relationships with the specified source element -- `relationship==*->`: all relationships with the specified destination element -- `relationship==->`: all relationships between the two specified elements - -Element and relationship expressions are not supported on dynamic views. - -### Plugins - -Plugins can be used where more control or customisation is required, and provide access to the workspace via the [Structurizr for Java library](https://github.com/structurizr/java). For example, you could use a plugin to create model elements based upon an external data source, or perhaps define views programmatically. Plugins can be used at any point in the DSL. - -To write a plugin, create a Java class that implements the `com.structurizr.dsl.StructurizrDslPlugin` interface (you will need to add a dependency on the DSL library, which can be found on Maven Central via `com.structurizr:structurizr-dsl`). - -``` -package com.example; - -import com.structurizr.Workspace; - -public class TestPlugin implements StructurizrDslPlugin { - - @Override - public void run(StructurizrDslPluginContext context) { - Workspace workspace = context.getWorkspace(); - workspace.setName("Name set by plugin"); - } - -} -``` - -The compiled plugin packaged as a JAR file (plus any other JAR dependencies) should be placed in a directory named `plugins` next to your DSL file. You can then use your plugin from the DSL using the `!plugin` keyword. - - ``` - workspace { - - !plugin com.example.TestPlugin - -} -``` - -Parameters can be specified in the plugin body, for example. - - ``` - workspace { - - !plugin com.example.TestPlugin { - name value - } - -} -``` - -The named parameters are then available via the `getParameter(name)` method of the `StructurizrDslPluginContext`object. - -### Scripts - -Scripts are like plugins, except they don't need to be compiled before use. JavaScript(*), Kotlin, Groovy, and Ruby are supported out of the box, and you can add more languages via the Java Scripting API. -Scripts can be used at any point in the DSL. - -The following variables are available from scripts: - -- `context`: a [StructurizrDslScriptContext](https://github.com/structurizr/dsl/blob/master/src/main/java/com/structurizr/dsl/StructurizrDslScriptContext.java) object with contextual information -- `workspace`: the [Workspace](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/Workspace.java) object -- `element`: the current [Element](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/model/Element.java) object, if the script is used within the scope of an element -- `relationship`: the current [Relationship](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/model/Relationship.java) object, if the script is used within the scope of a relationship -- `view`: the current [View](https://github.com/structurizr/java/blob/master/structurizr-core/src/com/structurizr/view/View.java) object, if the script is used within the scope of a view - -(*) Nashorn (the JVM JavaScript engine) is deprecated, see [https://openjdk.java.net/jeps/372](https://openjdk.java.net/jeps/372) for details. - -#### Inline scripts - -To use an inline script, use the `!script` keyword followed by the language you'd like to use (`groovy`, `kotlin`, `ruby`, or `javascript`). For example, the following Groovy script will create the default set of views, without automatic layout enabled. - -``` -!script groovy { - workspace.views.createDefaultViews() - workspace.views.views.findAll { it instanceof com.structurizr.view.ModelView }.each { it.disableAutomaticLayout() } -} -``` - -Please note that inline scripts cannot have a line that only contains a closing `}` character. - -#### External scripts - -To use an external script, create a script file next to your DSL file (e.g. `script.kts`). - -``` -workspace.views.createDefaultViews() -workspace.views.views.forEach { it.disableAutomaticLayout() } -``` - -You can then use your script from the DSL using the `!script` keyword. - -``` -!script script.kts -``` - -The following file extensions are recognised: - -- `.groovy` (Groovy) -- `.kts` (Kotlin) -- `.rb` (Ruby) -- `.js` (JavaScript) - -Parameters for external scripts can be specified as follows: - -``` -!script script.kts { - name value -} -``` - -## Grammar - -The following describes the language grammar, with angle brackets (`<...>`) used to show required properties, and square brackets (`[...]`) used to show optional properties. -Most statements are of the form: `keyword [optional properties]` - -### workspace - -`workspace` is the top level language construct, and the wrapper for the [model](#model) and [views](#views). A workspace can optionally be given a name and description. - -``` -workspace [name] [description] { - ... -} -``` - -A workspace can also extend another workspace, to add more elements, relationships, views, etc to it. - -``` -workspace extends { - ... -} -``` - -The base workspace can either be referenced using a local DSL/JSON file, or a remote (via a HTTPS URL) DSL/JSON file. -When extending a DSL-based workspace, all of the identifiers defined in that workspace are available to use in the extended workspace. - -Permitted children: - -- name -- description -- [properties](#properties) -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) -- [!identifiers](#identifier-scope) -- [!impliedRelationships](#impliedrelationships) -- [model](#model) -- [views](#views) -- [configuration](#configuration) - -### model - -Each workspace must contain a `model` block, inside which elements and relationships are defined. - -``` -model { - ... -} -``` - -Permitted children: - -- [group](#group) -- [person](#person) -- [softwareSystem](#softwareSystem) -- [deploymentEnvironment](#deploymentEnvironment) -- [element](#element) -- [-> (relationship)](#relationship) - -### enterprise - -__This concept has been deprecated - please use [group](#group) instead.__ - -The `enterprise` keyword provides a way to define a named "enterprise" (e.g. an organisation) within the top-level model. Any people or software systems defined inside this block will be deemed to be "internal", while all others will be deemed to be "external". On System Landscape and System Context diagrams, an enterprise is represented as a dashed box. Only a single enterprise can be defined within a model. - -``` -enterprise [name] { - ... -} -``` - -Permitted children: - -- [group](#group) -- [person](#person) -- [softwareSystem](#softwareSystem) -- [-> (relationship)](#relationship) - -### group - -The `group` keyword provides a way to define a named grouping of elements, which will be rendered as a boundary around those elements. -Groups can be nested; see [DSL Cookbook - Groups](cookbook/groups) for more information. - -``` -group { - ... -} -``` - -Groups can only be used to group elements of the same type (i.e. the same level of abstraction), as follows: - -| Location | Permitted elements | -|-----------------|-----------------------------| -| Model | People and software systems | -| Software System | Containers | -| Container | Components | - -See [Structurizr - Help - Notation](https://structurizr.com/help/notation) for a description of which groups are shown for a given diagram type. - -### person - -The `person` keyword defines a person (e.g. a user, actor, role, or persona). - -``` -person [description] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Person` - -Permitted children: - -- [description](#description) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [-> (relationship)](#relationship) - -### softwareSystem - -The `softwareSystem` keyword defines a software system. - -``` -softwareSystem [description] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Software System` - -Permitted children: - -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) -- [group](#group) -- [container](#container) -- [description](#description) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [-> (relationship)](#relationship) - -### container - -The `container` keyword defines a container, within a software system. - -``` -container [description] [technology] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Container` - -Permitted children: - -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) -- [group](#group) -- [component](#component) -- [description](#description) -- [technology](#technology) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [-> (relationship)](#relationship) - -### component - -The `component` keyword defines a component, within a container. - -``` -component [description] [technology] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Component` - -Permitted children: - -- [!docs](#documentation) -- [!adrs](#architecture-decision-records-adrs) -- [description](#description) -- [technology](#technology) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [-> (relationship)](#relationship) - -### deploymentEnvironment - -The `deploymentEnvironment` keyword provides a way to define a deployment environment (e.g. development, testing, staging, live, etc). - -``` -deploymentEnvironment { - ... -} -``` - -Permitted children: - - -- [group](#group) -- [deploymentGroup](#deploymentGroup) -- [deploymentNode](#deploymentNode) -- [-> (relationship)](#relationship) - -### deploymentGroup - -The `deploymentGroup` keyword provides a way to define a named deployment group. - -``` -deploymentGroup -``` - -When software system/container instances are added to a deployment environment, all of the relationships between these elements are automatically replicated between *all* instances. Deployment groups provide a way to restrict the scope in which relationships are replicated. -See [DSL cookbook - Deployment groups](https://github.com/structurizr/dsl/tree/master/docs/cookbook/deployment-groups) for an example. - -### deploymentNode - -The `deploymentNode` keyword is used to define a deployment node. - -``` -deploymentNode [description] [technology] [tags] [instances] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Deployment Node` - -Permitted children: - -- [group](#group) -- [deploymentNode](#deploymentNode) (deployment nodes can be nested) -- [infrastructureNode](#infrastructureNode) -- [softwareSystemInstance](#softwareSystemInstance) -- [containerInstance](#containerInstance) -- [-> (relationship)](#relationship) -- [description](#description) -- [technology](#technology) -- [instances](#instances) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) - -### infrastructureNode - -The `infrastructureNode` keyword defines an infrastructure node, which is typically something like a load balancer, firewall, DNS service, etc. - -``` -infrastructureNode [description] [technology] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` -- `Infrastructure Node` - -Permitted children: - -- [-> (relationship)](#relationship) -- [description](#description) -- [technology](#technology) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) - -### softwareSystemInstance - -The `softwareSystemInstance` keyword defines an instance of the specified software system that is deployed on the parent deployment node. - -``` -softwareSystemInstance [deploymentGroups] [tags] { - ... -} -``` - -The `identifier` must represent a software system. `deploymentGroups` is a comma seperated list of identifiers representing deployment groups. - -In addition to the software system's tags, the following tags are added by default: - -- `Software System Instance` - -Permitted children: - -- [-> (relationship)](#relationship) -- [description](#description) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [healthCheck](#healthCheck) - -### containerInstance - -The `containerInstance` keyword defines an instance of the specified container that is deployed on the parent deployment node. - -``` -containerInstance [deploymentGroups] [tags] { - ... -} -``` - -The `identifier` must represent a container. `deploymentGroups` is a comma seperated list of identifiers representing deployment groups. - -In addition to the container's tags, the following tags are added by default: - -- `Container Instance` - -Permitted children: - -- [-> (relationship)](#relationship) -- [description](#description) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [healthCheck](#healthCheck) - -### healthCheck - -The `healthCheck` keyword defines a HTTP health check for the parent software system/container instance. - -``` -healthCheck [interval] [timeout] -``` - -The interval is a number of seconds (default 60s), and the timeout is a number of milliseconds (default 0ms). - -### element - -The `element` keyword defines a [custom element](https://structurizr.com/help/custom-elements) (this is only available on the Structurizr cloud service/on-premises installation/Lite). - -``` -element [metadata] [description] [tags] { - ... -} -``` - -The following tags are added by default: - -- `Element` - -Permitted children: - -- [description](#description) -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) -- [-> (relationship)](#relationship) - -### relationship - -`->` is used to define a uni-directional relationship between two elements. - -There are two ways to define relationships. The first is explicitly, where you explicitly use a source identifier: - -``` - -> [description] [technology] [tags] { - ... -} -``` - -For example: - -``` -user -> softwareSystem "Uses" -``` - -And the second is implicitly, where the relationship source is the element in scope: - -``` --> [description] [technology] [tags] -``` - -For example: - -``` -person user { - -> softwareSystem "Uses" -} -``` - -This is equivalent to the following, where the special `this` identifier is used to refer to the element in scope: - -``` -person user { - this -> softwareSystem "Uses" -} -``` - -The following tags are added to relationships by default: - -- `Relationship` - -The following types of relationships can be created using the DSL: - -| Source | Destination | -| ------------- | ------------- | -| Person | Person, Software System, Container, Component | -| Software System | Person, Software System, Container, Component | -| Container | Person, Software System, Container, Component | -| Component | Person, Software System, Container, Component | -| Deployment Node | Deployment Node | -| Infrastructure Node | Deployment Node, Infrastructure Node, Software System Instance, Container Instance | -| Software System Instance | Infrastructure Node | -| Container Instance | Infrastructure Node | - -Permitted children: - -- [tags](#tags) -- [url](#url) -- [properties](#properties) -- [perspectives](#perspectives) - -### tags - -`tags` is used to add tags to an element or relationship. Tags can be specified comma separated, or individually. - -``` -tags "Tag 1" -tags "Tag 1,Tag 2" -tags "Tag 1" "Tag 2" -``` - -### description - -`description` is used to set the description on an element or view. - -``` -description "Description" -``` - -### technology - -`technology` is used to set the technology on a container, component, deployment node, infrastructure node. - -``` -technology "Technology" -``` - -### instances - -`instances` is used to set the number of instances of a deployment node. -This can either be a static number, or a range (e.g. 0..1, 1..3, 5..10, 0..N, 0..*, 1..N, 1..*, etc). - -``` -instances "4" -``` - -``` -instances "1..N" -``` - -### url - -`url` is used to set a URL on an element or relationship. - -``` -url https://example.com -``` - -### properties - -The `properties` block is used to define one or more name/value properties. - -``` -properties { - - ... -} -``` - -### perspectives - -The `perspectives` block is used to define one or more name/description perspectives for an element or relationship. -See [Help - Perspectives](https://structurizr.com/help/perspectives) for how these are used. - -``` -perspectives { - - ... -} -``` - -### !ref - -The `!ref` keyword provides a way to reference a previously defined element/relationship, and is designed to be used with the workspace `extends` or `!include` features. It can be used in a couple of ways. - -The first usage scenario is to reference an existing element/relationship that has been defined via the DSL. This allows you to extend the element referenced by the given identifier. - -``` -!ref { - ... -} -``` - -Or, if you're extending a JSON-based workspace, you can reference an element by its "canonical name", and assign that to an identifier. - -``` - = !ref { - ... -} -``` - -See [ref.dsl](../src/test/dsl/ref.dsl) for some usage examples. - -### views - -Each workspace can also contain one or more views, defined with the `views` block. - -``` -views { - ... -} -``` - -The `views` block can contain the following: - -- [systemLandscape](#systemLandscape-view) -- [systemContext](#systemContext-view) -- [container](#container-view) -- [component](#component-view) -- [filtered](#filtered-view) -- [dynamic](#dynamic-view) -- [deployment](#deployment-view) -- [custom](#custom-view) -- [image](#image-view) -- [styles](#styles) -- [theme](#theme) -- [themes](#themes) -- [branding](#branding) -- [terminology](#terminology) -- [properties](#properties) - -If a workspace doesn't have a `views` block, or the `views` block doesn't define any views, -a [default set of views](#convention-over-configuration-useful-defaults) will be defined for you. -Defining one or more views in the `views` block will remove this default set of views, -although they can be added back with a script if needed: - -``` -!script groovy { - workspace.views.createDefaultViews() -} -``` - -### systemLandscape view - -The `systemLandscape` keyword is used to define a [System Landscape view](https://c4model.com/#SystemLandscapeDiagram). - -``` -systemLandscape [key] [description] { - ... -} -``` - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### systemContext view - -The `systemContext` keyword is used to define a [System Context view](https://c4model.com/#SystemContextDiagram) for the specified software system. - -``` -systemContext [key] [description] { - ... -} -``` - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### container view - -The `container` keyword is used to define a [Container view](https://c4model.com/#ContainerDiagram) for the specified software system. - -``` -container [key] [description] { - ... -} -``` - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### component view - -The `component` keyword is used to define a [Component view](https://c4model.com/#ComponentDiagram) for the specified container. - -``` -component [key] [description] { - ... -} -``` - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### filtered view - -The `filtered` keyword is used to define a [Filtered view](https://structurizr.com/help/filtered-views) on top of the specified view. - -``` -filtered [key] [description] { - ... -} -``` - -The `baseKey` specifies the key of the System Landscape, System Context, Container, or Component view on which this filtered view should be based. The mode (`include` or `exclude`) defines whether the view should include or exclude elements/relationships based upon the `tags` provided. - -Please note that once a filtered view is defined for a given "base view", that base view will no longer show up in your diagram list when using the Structurizr renderer. This is by design. If you'd like to see the base view too, just create another filtered view for the same base view, which includes the `Element` and `Relationship` tags. - -Permitted children: - -- [default](#default) -- [title](#title) -- [description](#description) -- [properties](#properties) - -``` -filtered include "Element,Relationship" [key] [description] -``` - -### dynamic view - -The `dynamic` keyword defines a [Dynamic view](https://c4model.com/#DynamicDiagram) for the specified scope. - -``` -dynamic <*|software system identifier|container identifier> [key] [description] { - ... -} -``` - -The first property defines the scope of the view, and therefore what can be added to the view, as follows: - -- `*` scope: People and software systems. -- Software system scope: People, other software systems, and containers. -- Container scope: People, other software systems, other containers, and components. - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Unlike the other diagram types, Dynamic views are created by specifying the relationships that should be added to the view, within the `dynamic` block, as follows: - -``` - -> [description] [technology] - [description] -``` - -With a dynamic view, you're showing _instances_ of relationships that are defined in the static model. -For example, imagine that you have two software systems defined in the static model, with a single relationship between them described as "Sends data to". -A dynamic view allows you to override the relationship description, to better describe the interaction in the context of the behaviour you're diagramming. -See [dynamic.dsl](../src/test/dsl/dynamic.dsl) for an example of this, and [Modelling multiple relationships](https://dev.to/simonbrown/modelling-multiple-relationships-51bf) for some tips on how to best model multiple relationships between two elements in order to avoid cluttering your static model. - -See [DSL cookbook - Dynamic view](https://github.com/structurizr/dsl/tree/master/docs/cookbook/dynamic-view) and -[DSL cookbook - Dynamic view with parallel sequences](https://github.com/structurizr/dsl/tree/master/docs/cookbook/dynamic-view-parallel) -for examples. - -Permitted children: - -- [autoLayout](#autoLayout) -- [default](#default) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### deployment view - -The `deployment` keyword defines a [Deployment view](https://c4model.com/#DeploymentDiagram) for the specified scope and deployment environment. - -``` -deployment <*|software system identifier> [key] [description] { - ... -} -``` - -The first property defines the scope of the view, and the second property defines the deployment environment (which can be an identifier, or a name). The combination of these two properties determines what can be added to the view, as follows: - -- `*` scope: All deployment nodes, infrastructure nodes, and container instances within the deployment environment. -- Software system scope: All deployment nodes and infrastructure nodes within the deployment environment. Container instances within the deployment environment that belong to the software system. - -A view key will be generated for you if not specified; __automatically generated view keys are not guaranteed to be stable over time, and you will likely lose [manual layout information](https://structurizr.com/help/manual-layout) when using them in conjunction with Structurizr Lite/on-premises/cloud__. - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### custom view - -The `custom` keyword is used to define a [custom view](https://structurizr.com/help/custom-diagrams) (this is only available on the Structurizr cloud service/on-premises installation/Lite). - -``` -custom [key] [title] [description] { - ... -} -``` - -Permitted children: - -- [include](#include) -- [exclude](#exclude) -- [autoLayout](#autoLayout) -- [default](#default) -- [animation](#animation) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### image view - -The `image` keyword is used to define an [image view](https://structurizr.com/help/image-views) (this is only available on the Structurizr cloud service/on-premises installation/Lite). - -``` -image <*|element identifier> [key] { - ... -} -``` - -Inside this block you can define the source of the image, using one of the following: - -- `plantuml ` -- `mermaid ` -- `kroki ` (where `format` is the format identifier included in the URL path; e.g. `https://kroki.io/{format}/...`) -- `image ` - -You will need to provide a PlantUML/Mermaid/Kroki URL, and optionally a format (`png` or `svg`), -when using these services. These can be specified as view set properties: - -``` -views { - properties { - "plantuml.url" "http://localhost:7777" - "plantuml.format" "svg" - "mermaid.url" "http://localhost:8888" - "mermaid.format" "svg" - "kroki.url" "http://localhost:9999" - "kroki.format" "svg" - } - - ... -} -``` - -The public PlantUML (`https://plantuml.com/plantuml`), Mermaid (`https://mermaid.ink`), and Kroki (`https://kroki.io`) -URLs may work, but (1) please be aware that you are sending information to a third-party service and (2) these public services -may not correctly set the CORS headers required for image views to work (see the notes at [Structurizr - Help - Image views](https://structurizr.com/help/image-views)). - -See [DSL cookbook - Image view](https://github.com/structurizr/dsl/tree/master/docs/cookbook/image-view) and -the [image view tests](https://github.com/structurizr/dsl/tree/master/src/test/dsl/image-views) for some examples. - -Permitted children: - -- [default](#default) -- [title](#title) -- [description](#description) -- [properties](#properties) - -### include - -The `include` keyword can be used to include elements or relationships. - -#### Including elements - -To include elements in a view, use one or more `include` statements inside the block defining the view. - -``` -include <*|identifier|expression> [*|identifier|expression...] -``` - -Elements can either be specified using individual identifiers, the wildcard identifier (`*`), or a property expression. Please note that including elements will also include the relationships between those elements. - -The wildcard identifier (`*`) operates differently depending upon the type of diagram, as follows: - -- System Landscape view: Include all people and software systems. -- System Context view: Include the software system in scope; plus all people and software systems that are directly connected to the software system in scope. -- Container view: Include all containers within the software system in scope; plus all people and software systems that are directly connected to those containers. -- Component view: Include all components within the container in scope; plus all people, software systems and containers (belonging to the software system in scope) directly connected to them. -- Filtered view: (not applicable) -- Dynamic view: (not applicable) -- Deployment view: Include all deployment nodes, infrastructure nodes, and container instances defined within the deployment environment and (optional) software system in scope. - -They provide a way to include elements based upon some basic conditional logic, as follows: - -- `element.tag==,[tag]`: include elements that have all of the specified tags -- `element.tag!=,[tag]`: include elements that do not have all of the specified tags - -#### Including relationships - -To include a relationship in a view, you can specify an individual relationship identifier, or an expression: - -``` -include [identifier|expression...] -``` - -Relationship expressions only operate on elements that exist in the view. - -### exclude - -The `exclude` keyword can be used to exclude elements or relationships. - -#### Excluding elements - -To exclude specific elements, use one or more `exclude` statements inside the block defining the view. - -``` -exclude [identifier|expression...] -``` - -#### Excluding relationships - -To exclude a relationship in a view, you can specify an individual relationship identifier, or use a property expression: - -``` -exclude [identifier|expression...] -``` - -They provide a way to exclude relationships based upon some basic conditional logic, as follows: - -- `relationship.tag==,[tag]`: exclude relationships that have all of the specified tags -- `relationship.tag!=,[tag]`: exclude relationships that do not have all of the specified tags - -Alternatively, you can use the relationship expression syntax as follows (please note the double quotes surrounding the entire expression): - -``` -exclude "<*|identifier> -> <*|identifier>" -``` - -The combinations of parameters are: - -- `* -> *`: all relationships between all elements -- `source -> *`: all relationships from `source` to any element -- `* -> destination`: all relationships from any element to `destination` -- `source -> destination`: all relationships from `source` to `destination` - -The relationship expression syntax only operates on elements that exist in the view. - -### autoLayout - -To enable automatic layout mode for the diagram, use the `autoLayout` statement inside the block defining the view. - -``` -autoLayout [tb|bt|lr|rl] [rankSeparation] [nodeSeparation] -``` - -The first property is the rank direction: - -- `tb`: Top to bottom (default) -- `bt`: Bottom to top -- `lr`: Left to right -- `rl`: Right to left - -The second property is the separation of ranks in pixels (default: `300`), while the third property is the separation of nodes in the same rank in pixels (default: `300`). - -Please note that if your DSL workspace does not explicitly define any views, the DSL parser will automatically create a default set of views for you, with auto-layout enabled. -To change this behaviour, you can either (1) explicitly define your views or (2) use a script to disable automatic layout ([example](https://github.com/structurizr/dsl/tree/master/docs/cookbook/scripts#create-the-default-views-without-automatic-layout)). - -### default - -Sets the default view to be shown. - -``` -default -``` - -### animation - -The `animation` keyword defines the animation for the specified view. -Each animation step should be defined on a separate line, inside the block, specifying the elements that should be included in that step. - -``` -animation { - [identifier...] - [identifier...] -} -``` - -### title - -Overrides the title of the view. - -``` -title -``` - -### styles - -`styles` is the wrapper for one or more element/relationship styles, which are used when rendering diagrams. - -``` -styles { - ... -} -``` - -Permitted children: - -- [element](#element-style) -- [relationship](#relationship-style) - -### element style - -The `element` keyword is used to define an element style. -All nested properties (`shape`, `icon`, etc) are optional. - -``` -element <tag> { - shape <Box|RoundedBox|Circle|Ellipse|Hexagon|Cylinder|Pipe|Person|Robot|Folder|WebBrowser|MobileDevicePortrait|MobileDeviceLandscape|Component> - icon <file|url> - width <integer> - height <integer> - background <#rrggbb|color name> - color <#rrggbb|color name> - colour <#rrggbb|color name> - stroke <#rrggbb|color name> - strokeWidth <integer: 1-10> - fontSize <integer> - border <solid|dashed|dotted> - opacity <integer: 0-100> - metadata <true|false> - description <true|false> - properties { - name value - } -} -``` - -See the following links for details about how to use element styles: - -- [DSL cookbook - Element styles](https://github.com/structurizr/dsl/tree/master/docs/cookbook/element-styles) -- [DSL cookbook - Groups](https://github.com/structurizr/dsl/tree/master/docs/cookbook/groups) -- [Structurizr - Notation](https://structurizr.com/help/notation) - -Notes: - -- Colors can be specified as a hex code (e.g. `#ffff00`) or a CSS/HTML named color (e.g. `yellow`). -- See [Help - Icons](https://structurizr.com/help/icons) for information about HTTPS/CORS if you are using the Structurizr cloud service/on-premises installation/Lite and specifying an element style icon via a URL. -- Element styles are designed to work with the Structurizr cloud service/on-premises installation/Lite, and may not be fully supported by the [PlantUML, Mermaid, etc export formats](https://github.com/structurizr/export) (e.g. shapes and icons). - -### relationship style - -The `relationship` keyword is used to define a relationship style. -All nested properties (`thickness`, `color`, etc) are optional. - -``` -relationship <tag> { - thickness <integer> - color <#rrggbb|color name> - colour <#rrggbb|color name> - style <solid|dashed|dotted> - routing <Direct|Orthogonal|Curved> - fontSize <integer> - width <integer> - position <integer: 0-100> - opacity <integer: 0-100> - properties { - name value - } -} -``` - -See the following links for details about how to use element styles: - -- [DSL cookbook - Relationship styles](https://github.com/structurizr/dsl/tree/master/docs/cookbook/relationship-styles) -- [Structurizr - Notation](https://structurizr.com/help/notation) - -Notes: - -- Colors can be specified as a hex code (e.g. `#ffff00`) or a CSS/HTML named color (e.g. `yellow`). -- Relationship styles are designed to work with the Structurizr cloud service/on-premises installation/Lite, and may not be fully supported by the [PlantUML, Mermaid, etc export formats](https://github.com/structurizr/export) (e.g. line/arrow colours). - -### theme - -The `theme` keyword can be used to specify a theme that should be used when rendering diagrams. See [Structurizr - Themes](https://structurizr.com/help/themes) for more details. - -``` -theme <default|url> -``` - -`default` can be used as a theme URL, to include [the default Structurizr theme](https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/default/theme.json). - -### themes - -The `themes` keyword can be used to specify one or more themes that should be used when rendering diagrams. See [Structurizr - Themes](https://structurizr.com/help/themes) for more details. - -``` -themes <url> [url] ... [url] -``` - -`default` can be used as a theme URL, to include [the default Structurizr theme](https://structurizr.com/help/theme?url=https://static.structurizr.com/themes/default/theme.json). - -### branding - -The `branding` keyword allows you to define some custom branding that should be used when rendering diagrams and documentation. See [Structurizr - Branding](https://structurizr.com/help/branding) for more details. - -``` -branding { - logo <file|url> - font <name> [url] -} -``` - -Notes: - -- See [Help - Icons](https://structurizr.com/help/icons) for information about HTTPS/CORS if you are using the Structurizr cloud service/on-premises installation/Lite and specifying a branding icon via a URL. - -### terminology - -The `terminology` keyword allows you to override the terminology used when rendering diagrams. - -``` -terminology { - person <term> - softwareSystem <term> - container <term> - component <term> - deploymentNode <term> - infrastructureNode <term> - relationship <term> -} -``` - -### configuration - -Finally, there are some configuration options that can be specified inside the `configuration` block. - -``` -configuration { - ... -} -``` - -Permitted children: - -- [visibility](#visibility) -- [users](#users) -- [properties](#properties) - -### visibility - -The `visibility` keyword can be used to set the [visibility of the workspace](https://structurizr.com/help/workspace-sharing). - -``` -visibility <private|public> -``` - -### users - -The `users` block can be used to specify the users who should have read-only or read-write access to a workspace. Each username (e.g. e-mail address) and role pair should be specified on their own line. Valid roles are `read` (read-only) and `write` (read-write). - -``` -users { - <username> <read|write> -} -``` - -## Documentation - -The `!docs` keyword can be used to attach Markdown/AsciiDoc documentation to the parent context (either the workspace, a software system, or a container). - -``` -!docs <path> [fully qualified class name] -``` - -The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: - -``` -!docs subdirectory -``` - -By default, the [com.structurizr.importer.documentation.DefaultDocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DefaultDocumentationImporter.java) class will be used to import documentation as follows: - -- All Markdown and AsciiDoc files in the given directory will be imported, alphabetically according to the filename. -- All images in the given directory (and sub-directories) are also imported into the workspace. -- See [Structurizr - Documentation - Headings and sections](https://structurizr.com/help/documentation/headings) for details about how section headings and numbering are handled. - -The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/importer/documentation/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. - -## Architecture decision records (ADRs) - -The `!adrs` keyword can be used to attach Markdown/AsciiDoc ADRs to the parent context (either the workspace, a software system, or a container). - -``` -!adrs <path> [fully qualified class name] -``` - -The path must be a relative path, located within the same directory as the parent file, or a subdirectory of it. For example: - -``` -!adrs subdirectory -``` - -By default, the [com.structurizr.documentation.importer.AdrToolsDecisionImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/AdrToolsDecisionImporter.java) class will be used to import ADRs as follows: - -- All Markdown files in this directory will be imported, alphabetically according to the filename. -- The files must have been created by [adr-tools](https://github.com/npryce/adr-tools), or at least follow the same format. -- All images in the given directory (and sub-directories) are also imported into the workspace. - -The above behaviour can be customised by specifying the fully qualified class name of your own implementation of [DocumentationImporter](https://github.com/structurizr/documentation/blob/main/src/main/java/com/structurizr/documentation/importer/DocumentationImporter.java), which needs to be on the DSL classpath or installed as a JAR file in the `plugins` directory next to your DSL file. +This documentation has moved to [https://docs.structurizr.com/dsl/language](https://docs.structurizr.com/dsl/language). \ No newline at end of file