Here are some suggested steps for incorporating Structurizr into your workflow. Regardless of which authoring method you use, your workspace is stored on the cloud service/on-premises installation as a JSON file (OpenAPI schema). This JSON file can be exported in a number of ways - see Help - Workspace export and import for more details.

Code or text

The client libraries and Structurizr CLI take the input format used for authoring your workspace (e.g. Java code, C# code, DSL, etc) and convert that to a workspace JSON file. The client libraries and Structurizr CLI then push this JSON file to the cloud service/on-premises installation, where it is stored.

When using code or text, you should treat the uploaded workspace as immutable (with the exception of modifying diagram layout; see below). Any changes that you want to make to your workspace should be made by changing the workspace source (i.e. the code or text).

The only exception to this immutability rule is diagram layout, assuming you're not using automatic layout. When you open the diagram editor, you'll be able to move elements around the diagram canvas. These layout changes are stored inside the workspace JSON file. Before you push a new version of your workspace, the client libraries and Structurizr CLI will pull a copy of your existing workspace JSON down to your computer, and attempt to extract the diagram layout information for inclusion in the new version of your workspace. The algorithm for doing this varies between client library implementations. For this reason, you may want to version control both your input code/text (this creates your workspace), and an export of the workspace JSON file (this contains your diagram layout information).