Doc updates.

structurizr · Oct 7, 2024 · a39fee1 · a39fee1
1 parent ea4f3b7
commit a39fee1
Show file tree

Hide file tree

Showing 23 changed files with 222 additions and 44 deletions.
diff --git a/dsl/09-workspace-extension.md b/dsl/09-workspace-extension.md
@@ -8,6 +8,10 @@ permalink: /dsl/workspace-extension
 
 # Workspace extension
 
-...
+The Structurizr DSL provides a way to extend an existing workspace, enabling you to reuse common elements/relationships
+across multiple workspaces.
 
-See [DSL Cookbook - Workspace extension](/dsl/cookbook/workspace-extension/) for more.
+## Links
+
+- [DSL Cookbook - Workspace extension](/dsl/cookbook/workspace-extension/)
+- [Usage - Enterprise](/usage/enterprise)
diff --git a/images/example-1.png b/images/example-1.png
diff --git a/images/example-2.png b/images/example-2.png
diff --git a/index.md b/index.md
@@ -9,21 +9,13 @@ permalink: /
 # Structurizr
 
 Structurizr builds upon "diagrams as code", allowing you to create
-__multiple software architecture diagrams__, in a __variety of rendering tools__, from a __single model__.
+__multiple software architecture diagrams__ using the [C4 model](https://c4model.com), in a __variety of rendering tools__,
+from a __single model__.
 
 <div style="text-align: center">
 <iframe src="https://www.youtube-nocookie.com/embed/LYzOc7vI-Uo?si=Fiwayepq9xOKpgeK" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 </div>
 
-## C4 model
-
-Structurizr is specifically designed to support the [C4 model for visualising software architecture](https://c4model.com),
-allowing you to reach the highest levels of maturity associated with creating software architecture diagramming.
-
-![Software architecture diagram maturity model](images/software-architecture-diagramming-maturity-model.png)
-
-## Model-based
-
 Structurizr is a modelling tool, allowing you to create multiple diagrams from a single model.
 Here's an example with the [Structurizr DSL](/dsl):
 
@@ -63,36 +55,8 @@ workspace {
 }
 ```
 
-## Authoring tool independent
-
-The [Structurizr DSL](/dsl) shown above is just one way to author your software architecture models.
-There are also a number of programming language libraries (e.g. [Structurizr for Java](/java),
-and ports for [.NET, Python, PHP, TypeScript, etc](/community#authoring-tools))
-that can be used to create software architecture models.
-The [open JSON data format](https://github.com/structurizr/json) defines the data format for a Structurizr compatible "workspace",
-which is the wrapper for a software architecture model and views.
-
-With this in mind, Structurizr workspaces can be created in the following ways:
-
-1. Manually authored:
- - Using the [Structurizr DSL](/dsl).
- - Using [Structurizr for Java](/java).
-2. Reverse-engineered:
- - Using [Structurizr for Java](/java) or one of the ports for [.NET, Python, PHP, TypeScript, etc](/community#authoring-tools) to write a program to reverse-engineer model information from source code, deployment scripts, your live deployment environment, logs, traces, telemetry data, etc).
-3. Hybrid approach:
- - Use the Structurizr DSL to define software systems and containers, and reverse-engineer component level details via code.
- - Use code to reverse-engineer a system catalog from Backstage, ServiceNow, etc and have teams add container and component level detail via the Structurizr DSL.
-
-## Rendering tool independent
+This creates the following diagrams:
 
-Unlike most modelling tools, and because of the open JSON data format, Structurizr is rendering tool independent.
-For example, here are a number of visualisations of the same model.
+![](/images/example-1.png)
 
-|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Structurizr cloud service, on-premises installation, and Lite - diagram with manual layout | [![Structurizr - diagram with manual layout](images/structurizr-diagram-manual.png)](https://structurizr.com/share/36141/diagrams#Containers) |
-| Structurizr cloud service, on-premises installation, and Lite - diagram with automatic layout | [![Structurizr - diagram with automatic layout](images/structurizr-diagram-automatic.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=diagram) |
-| Structurizr cloud service, on-premises installation, and Lite - graph (interactive layout) | [![Structurizr - graph](images/structurizr-graph.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=graph) |
-| PlantUML via the Structurizr CLI (automatic layout only) | [![PlantUML via the Structurizr CLI](images/plantuml.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=plantuml) |
-| C4-PlantUML via the Structurizr CLI (automatic layout only) | [![C4-PlantUML via the Structurizr CLI](images/c4plantuml.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=c4plantuml) |
-| Mermaid via the Structurizr CLI (automatic layout only) | [![Mermaid via the Structurizr CLI](images/mermaid.jpg)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=mermaid) |
-| Ilograph via the Structurizr CLI (interactive layout) | [![Ilograph via the Structurizr CLI](images/ilograph.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=ilograph) |
+![](/images/example-2.png)
diff --git a/java/component/images/spring-petclinic-1.png b/java/component/images/spring-petclinic-1.png
diff --git a/java/component/introduction.md b/java/component/introduction.md
@@ -0,0 +1,40 @@
+---
+layout: default
+title: Introduction
+nav_order: 11
+parent: Component finder
+grand_parent: Structurizr for Java
+has_children: true
+permalink: /java/component/introduction
+has_toc: false
+---
+
+# Introduction
+
+This page introduces the basic theory and concepts behind the Structurizr component finder in the context
+of the [Spring PetClinic](https://github.com/spring-projects/spring-petclinic) application - a sample codebase that illustrates how to build a Java web application using 
+the Spring MVC framework. From a non-technical perspective, it's a software system designed for an imaginary pet clinic 
+that stores information about pets and their owners, visits made to the clinic, and the vets who work there. The system 
+is only designed to be used by employees of the clinic. From a technical perspective, the Spring PetClinic system 
+consists of a web application and a relational database schema. From a structural perspective, this codebase is a 
+traditional layered architecture. 
+
+Reverse-engineering this codebase into a UML class diagram generates the following diagram, showing all classes 
+and interfaces.
+
+[![](./images/spring-petclinic-1.png)](./images/spring-petclinic-1.png)
+
+In terms of the C4 model, this is level 4 - the code. To zoom-out and generate a component diagram at level 3, we need 
+to define a set of rules that we can use to identify components. These rules can then be codified using the Structurizr
+component finder to make this an automated process. This is a multi-step process, and may require more than a single 
+iteration as you explore and learn more about the codebase:
+
+1. Identify components
+1. Categorise components
+1. Define component identification rules
+
+At this point it's worth noting that since every codebase is unique, it's almost impossible to create a generic set of 
+rules that can be blindly applied to all codebases. Component identification therefore requires some knowledge of the 
+codebase so that the appropriate rules and heuristics can be applied.
+
+Early access to the remainder of this introduction is available via the [Structurizr Patreon](https://patreon.com/structurizr).
diff --git a/lite/01-quickstart.md b/lite/01-quickstart.md
@@ -41,7 +41,6 @@ you should see the diagram editor:
 
 At startup, Structurizr Lite created a file named `workspace.dsl` in your Structurizr data directory as a starting point.
 This is a Structurizr workspace, defined using the [Structurizr DSL](/dsl).
-It defines a model consisting of a user using a software system, and a single C4 model system context view.
 
 ## 4. Make some changes
 

diff --git a/lite/images/getting-started.png b/lite/images/getting-started.png
diff --git a/usage/authoring.md b/usage/authoring.md
@@ -0,0 +1,51 @@
+---
+layout: default
+title: Authoring
+parent: Usage
+nav_order: 2
+permalink: /usage/authoring
+---
+
+# Authoring
+
+Structurizr workspaces can be authored using a number of compatible tools, with workspace content being
+defined manually or automatically.
+
+## Tooling
+
+At the time of writing, Structurizr workspaces can be authored using the following tools:
+
+1. The [Structurizr DSL](/dsl) - a text-based DSL.
+2. One of the programming language libraries - [Structurizr for Java](/java) and the various ports for [.NET, Python, PHP, TypeScript, etc](/community#authoring-tools).
+
+The recommended approach for most teams is to use the Structurizr DSL - it results in more concise workspace definitions
+than using a programming language, and it's generally easier for a wider audience to understand.
+The Structurizr DSL is also a wrapper around the Structurizr for Java library, which you can gain access to via
+the [scripts](/dsl/scripts) and [plugins](/dsl/plugins) for enhanced flexibility.
+
+Irrespective of which authoring tool you use, the output is a workspace that can be serialised to a JSON document
+via an [open JSON data format](https://github.com/structurizr/json),
+which in turn can be [rendered via a variety of tools](/usage/rendering).
+
+## Manual authoring vs reverse-engineering
+
+The typical approach taken by teams is to manually author their workspace.
+For example, if you're using the Structurizr DSL, you are explicitly defining all people, software systems,
+containers, components, etc using the DSL language. This can be quick and effective, but requires that the DSL 
+definition is changed, and kept up to date, whenever the software architecture changes.
+
+Most people understand that diagrams will drift out of sync with reality over time.
+For this reason, it's possible for parts of the software architecture model (and therefore the diagrams)
+to be created via reverse-engineering techniques. For example:
+
+- __System landscape and context diagrams__: Use existing system/service catalogs (e.g. Backstage, ServiceNow, etc) as a source of data for identifying software systems and relationships.
+- __Container diagrams__: Parse log files or use OpenTelemetry data as a source of data for identifying applications/services and relationships.
+- __Component diagrams__: Static analysis/reverse-engineering of code as a source of data for identifying components and their relationships.
+- __Deployment diagrams__: Parse “infrastructure as code” definitions (e.g. Terraform, CloudFormation, etc) or reverse-engineer cloud environment configuration as a source of data for identifying deployment elements.
+
+Some of these techniques are not necessarily straightforward and require some up front engineering effort,
+which is why there is a lack of off-the-shelf tooling to support such use cases.
+Some organisations *are* building tools to do this internally, although they don't tend to share them with the community.
+The exception here is the [component finder](/java/component/) built into the Structurizr for Java library.
+Generally speaking, you will need to write some code that connects to APIs or parses files, and creates model
+elements/relationships programmatically.
diff --git a/usage/enterprise.md b/usage/enterprise.md
@@ -0,0 +1,41 @@
+---
+layout: default
+title: Enterprise
+parent: Usage
+nav_order: 4
+permalink: /usage/enterprise
+---
+
+# Enterprise
+
+Usage across an entire enterprise tends to stem from one of the following scenarios:
+
+- __Top-down__: The organisation has made a conscious decision to adopt the C4 model and the Structurizr tooling, and are mandating usage by all teams.
+- __Bottom-up__: One or more teams have found the C4 model and Structurizr useful, and want to spread adoption across more teams.
+
+Irrespective of how the tooling is introduced, you will likely come across one or both of the following scenarios at
+some point:
+
+1. Each team is modelling their own software systems, but they are all using shared software systems/services such as authentication. How do we ensure consistency (e.g. naming) across all teams?
+2. Each team is modelling their own software systems, which will include the relationships to other software systems owned by other teams. Decentralised workspace authoring works well, but an organisation would still like a centralised landscape view across the enterprise.
+
+[![](images/enterprise-1.png)](images/enterprise-1.png)
+
+One potential solution to this problem is to create a single workspace that covers the entire enterprise, assembled
+by asking individual teams to provide only their part of the software architecture model. 
+If using the Structurizr DSL, you might create a single workspace that uses the `!include` keyword to include the DSL
+fragment provided by each team. This can work across a small number of teams, but rapidly breaks down at scale.
+
+A better approach is as follows:
+
+1. Create a single shared "system catalog" workspace that defines all the people and software systems across all teams.
+2. Ask each team to [extend](/dsl/workspace-extension) this system catalog workspace, and add detail to describe their software system via the [!element](/dsl/language#element-1) keyword.
+3. Ask each team to publish their workspace to a single on-premises installation.
+4. Automatically generate a landscape workspace by aggregating all the software systems, people, and relationships from all published workspaces.
+
+There are several implementation strategies for achieving this, which will covered on the
+[Structurizr Patreon](https://patreon.com/structurizr) in the coming weeks.
+
+|---|---|
+| [![](images/enterprise-2.png)](images/enterprise-2.png) | [![](images/enterprise-3.png)](images/enterprise-3.png) |
+
diff --git a/usage/images/c4plantuml.png b/usage/images/c4plantuml.png
diff --git a/usage/images/enterprise-1.png b/usage/images/enterprise-1.png
diff --git a/usage/images/enterprise-2.png b/usage/images/enterprise-2.png
diff --git a/usage/images/enterprise-3.png b/usage/images/enterprise-3.png
diff --git a/usage/images/ilograph.png b/usage/images/ilograph.png
diff --git a/usage/images/mermaid.jpg b/usage/images/mermaid.jpg
diff --git a/usage/images/plantuml.png b/usage/images/plantuml.png
diff --git a/usage/images/structurizr-diagram-automatic.png b/usage/images/structurizr-diagram-automatic.png
diff --git a/usage/images/structurizr-diagram-manual.png b/usage/images/structurizr-diagram-manual.png
diff --git a/usage/images/structurizr-graph.png b/usage/images/structurizr-graph.png
diff --git a/usage/index.md b/usage/index.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Usage
+nav_order: 6
+has_children: true
+permalink: /usage
+has_toc: false
+---
+
+# Usage
+
+Given the variety of [products](/products) and [community tooling](/community), there are many ways in which the
+Structurizr tooling can be used. This section will look at usage from a few different angles:
+
+- [Workspace authoring](/usage/authoring)
+- [Workspace rendering](/usage/rendering)
+- Single team usage
+- Enterprise usage
diff --git a/usage/rendering.md b/usage/rendering.md
@@ -0,0 +1,33 @@
+---
+layout: default
+title: Rendering
+parent: Usage
+nav_order: 3
+permalink: /usage/rendering
+---
+
+# Rendering
+
+Unlike most modelling tools, and because of the open JSON data format, Structurizr is rendering tool independent.
+For example, here are a number of visualisations of the same model/views.
+
+|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Structurizr cloud service, on-premises installation, and Lite - diagram with manual layout | [![Structurizr - diagram with manual layout](images/structurizr-diagram-manual.png)](https://structurizr.com/share/36141/diagrams#Containers) |
+| Structurizr cloud service, on-premises installation, and Lite - diagram with automatic layout | [![Structurizr - diagram with automatic layout](images/structurizr-diagram-automatic.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=diagram) |
+| Structurizr cloud service, on-premises installation, and Lite - graph (interactive layout) | [![Structurizr - graph](images/structurizr-graph.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=graph) |
+| PlantUML via the Structurizr CLI (automatic layout only) | [![PlantUML via the Structurizr CLI](images/plantuml.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=plantuml) |
+| C4-PlantUML via the Structurizr CLI (automatic layout only) | [![C4-PlantUML via the Structurizr CLI](images/c4plantuml.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=c4plantuml) |
+| Mermaid via the Structurizr CLI (automatic layout only) | [![Mermaid via the Structurizr CLI](images/mermaid.jpg)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=mermaid) |
+| Ilograph via the Structurizr CLI (interactive layout) | [![Ilograph via the Structurizr CLI](images/ilograph.png)](https://structurizr.com/dsl?example=big-bank-plc&view=Containers&renderer=ilograph) |
+
+## Tooling
+
+There are three basic categories of rendering tools:
+
+- __Structurizr Lite/on-premises installation/cloud service__: These are the "original" browser-based rendering tools and support the largest feature set. See [Products](/products) for an overview of the different intended use cases and features.
+- __PlantUML, Mermaid, D2, WebSequenceDiagrams, Ilograph, etc__ via the __Structurizr CLI__: These "export" formats provide a wide range of compatability with existing tools. See [Exporters - Comparison](/export/comparison) for a comparison of the formats and features.
+- __Community tools__: These embed the browser-based UI from Structurizr Lite, etc or the export formats to provide a different tooling experience. See [Community tooling - Rendering tools](/community#rendering-tools) for a full list.
+
+If you have Docker or Java installed, the easiest tool to get started with is Structurizr Lite, which is designed to be
+used primarily for a quick roundtrip experience when authoring workspaces via the Structurizr DSL.
+See [Structurizr Lite - Quickstart](/lite/quickstart) for more details.
diff --git a/usage/team.md b/usage/team.md
@@ -0,0 +1,28 @@
+---
+layout: default
+title: Team
+parent: Usage
+nav_order: 3
+permalink: /usage/team
+---
+
+# Team
+
+Most adoption starts from a single team within an organisation - they are looking for a tool to create software
+architecture diagrams of the software system they are building, and have decided to progress away from diagramming
+tools (e.g. Visio, draw.io, PlantUML, Mermaid, etc) to a modelling tool.
+See [C4 model - Tooling - Diagramming vs modelling](https://c4model.com/tooling#diagramming-vs-modelling)
+for an explanation of the difference.
+
+The approach you take will vary based upon the [authoring tool](/usage/authoring) and
+[rendering tool](/usage/rendering) that you are using.
+If you are using the Structurizr DSL in conjunction with Structurizr Lite though, a recommended starting point is
+to simply store the content of your Structurizr data directory (i.e. your `workspace.dsl` and `workspace.json` files)
+in version control, next to your source code, along with a script to start up Structurizr Lite.
+This way, anybody on the team can see and modify the diagrams.
+
+If you need to publish your diagrams to a wider audience (e.g. non-technical people, or those without access to your
+source code repository), consider publishing the workspace to a [Structurizr on-premises installation](/onpremises)
+or the [cloud service](/cloud). Publishing a workspace can be achieved via the
+[Structurizr CLI push command](/cli/push). This can be done manually, or scripted and integrated into your build
+pipeline, a GitHub Action, post-commit hook, etc.