Structurizr

https://docs.structurizr.com/
Admin
Structurizr is a "diagrams as code" tool that allows users to create multiple software architecture...
Tokens:140,087
Snippets:1,541
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start playground with Docker (quickstart)

Source: https://docs.structurizr.com/playground

Pulls and runs the Structurizr playground Docker image, mapping port 8080. Requires Docker installed.

```bash
docker pull structurizr/structurizr
docker run -it --rm -p 8080:8080 structurizr/structurizr playground
```

--------------------------------

### Start Structurizr with Docker (example path)

Source: https://docs.structurizr.com/local/quickstart

Example of starting Structurizr when the data directory is located at /Users/simon/structurizr. Uses the same Docker commands with the concrete path substituted for PATH.

```bash
docker pull structurizr/structurizr
docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/structurizr local
```

--------------------------------

### Create a workspace and get the model

Source: https://docs.structurizr.com/java/getting-started

Creates a workspace and retrieves its model. The workspace is named "Getting Started" with a description.

```java
Workspace workspace = new Workspace("Getting Started", "This is a model of my software system.");
Model model = workspace.getModel();
```

--------------------------------

### Start Structurizr Lite with a specific data directory

Source: https://docs.structurizr.com/lite/quickstart

Example command for starting Structurizr Lite when the data directory is /Users/simon/structurizr.

```bash
docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/lite
```

--------------------------------

### Example roles file entries

Source: https://docs.structurizr.com/onpremises/authentication/file

Example entries for the structurizr.roles file, assigning roles to users alice and bob.

```text
alice=role1
bob=role2

```

--------------------------------

### Run Structurizr Lite Docker with example path

Source: https://docs.structurizr.com/lite/installation

Example Docker command using a specific data directory path (/Users/simon/structurizr).

```bash
docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/lite

```

--------------------------------

### Scoop install

Source: https://docs.structurizr.com/cli/installation

Adds the extras bucket and installs the Structurizr CLI via Scoop on Windows.

```bash
scoop bucket add extras
scoop install structurizr-cli
```

--------------------------------

### Example user file entries

Source: https://docs.structurizr.com/onpremises/authentication/file

Example entries for the structurizr.users file, showing two users with their bcrypt hashed passwords.

```text
alice=$2a$06$uM5wM.eJwrPq1RM/gBXRr.d0bfyu9ABxdE56qYbRLSCZzqfR7xHcC
bob=$2a$10$1SIlopeot3Tsyxt5wHAwo.WBQd8PWd.N4rKKM2I89HZIX.R6/idbe

```

--------------------------------

### Start Structurizr with Docker (using PATH placeholder)

Source: https://docs.structurizr.com/local/quickstart

Starts Structurizr locally using the pre-built Docker image. Replace PATH with the path to your Structurizr data directory. The command pulls the image and runs it, mapping port 8080 and mounting the data directory.

```bash
docker pull structurizr/structurizr
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/structurizr local
```

--------------------------------

### Run Structurizr Lite Spring Boot with example path

Source: https://docs.structurizr.com/lite/installation

Example Spring Boot command using a specific data directory path (/Users/simon/structurizr).

```bash
java -jar structurizr-lite.war /Users/simon/structurizr

```

--------------------------------

### Run Structurizr on-premises with example data directory

Source: https://docs.structurizr.com/onpremises/installation

Example Docker run command using a specific data directory path (/Users/simon/structurizr).

```bash
docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr structurizr/onpremises
```

--------------------------------

### workspace.dsl for software system A

Source: https://docs.structurizr.com/workspaces/enterprise

Example Structurizr DSL workspace for software system A, showing the model, views, styles, and configuration. It defines software systems A, B, and C, with containers for A and relationships between them. Use this as a starting point for teams adopting Structurizr.

```dsl
workspace "A" {

    !identifiers hierarchical

    model {
        a = softwareSystem "A" "A description of software system A." {
            app = container "Web Application" {
                technology "Java and Spring Boot"
            }
            db = container "Database Schema" {
                technology "MySQL"
                tag "Database"
            }

            app -> db "Reads from and writes to"
        }

        b = softwareSystem "B" "A description of software system B."
        c = softwareSystem "C" "A description of software system C." 

        a.app -> b "Requests data of type B from"
        a.app -> c "Requests data of type C from"
    }
    
    views {
        systemContext a "SystemContext" {
            include *
        }

        container a "Containers" {
            include *
        }

        styles {
            element "Database" {
                shape cylinder
            }
        }
    }

    configuration {
        scope softwaresystem
    }
    
}
```

--------------------------------

### Clone repositories and build with Gradle

Source: https://docs.structurizr.com/onpremises/building

Clones the onpremises and ui repositories, then runs the ui.sh script and Gradle build. The integration tests use Testcontainers to start Elasticsearch; if Docker is not installed, use `./gradlew clean build -x integrationTest` to exclude them. A successful build produces `structurizr-onpremises.war` in `structurizr-onpremises/build/libs`.

```bash
git clone --recursive https://github.com/structurizr/onpremises.git structurizr-onpremises
git clone https://github.com/structurizr/ui.git structurizr-ui
cd structurizr-onpremises
./ui.sh
./gradlew clean build

```

--------------------------------

### Homebrew install

Source: https://docs.structurizr.com/cli/installation

Installs the Structurizr CLI via Homebrew on macOS.

```bash
brew install structurizr-cli
```

--------------------------------

### FreeIPA LDAP configuration

Source: https://docs.structurizr.com/onpremises/authentication/ldap

Example configuration for FreeIPA, using the demo server ipa.demo1.freeipa.org. Useful for testing LDAP integration.

```xml
<ldap-server url="ldap://ipa.demo1.freeipa.org:389/dc=demo1,dc=freeipa,dc=org" />
<authentication-manager>
<ldap-authentication-provider
        user-search-base="cn=users,cn=accounts"
        user-search-filter="(uid={0})"
        group-search-base="cn=groups,cn=compat"
        group-search-filter="(memberUid={1})"
        role-prefix="ROLE_">
</ldap-authentication-provider>
</authentication-manager>
```

--------------------------------

### Example 1: Adding a banner to all pages

Source: https://docs.structurizr.com/onpremises/customisation

Adds a banner to all pages of the on-premises installation. The CSS defines the banner's appearance, and the JavaScript inserts the banner content on document ready. Place these files in the Structurizr data directory.

```css
#banner {
    background: gray;
    color: white;
    border-top: 10px solid white;
    padding: 10px;
}

#banner a {
    color: white;
}

```

```javascript
$(document).ready(function() {
    $('#banner').html('Please remember to register all new software systems at <a href="backstage.example.com" target="_blank">https://backstage.example.com</a>');
});

```

--------------------------------

### Start Structurizr with Docker

Source: https://docs.structurizr.com/binaries

Runs the Structurizr Docker container, mounting the current directory to /usr/local/structurizr. Replace <command> and [parameters] with the desired Structurizr command and arguments.

```bash
docker run -it --rm -v $PWD:/usr/local/structurizr structurizr/structurizr <command> [parameters]

```

--------------------------------

### Create a Java class with main method

Source: https://docs.structurizr.com/java/getting-started

Starter class with a main method where Structurizr code will be added. The main method throws Exception to allow workspace operations.

```java
public class GettingStarted {

    public static void main(String[] args) throws Exception {
       // your Structurizr code will go here
    }

}
```

--------------------------------

### Embed diagram with parameters

Source: https://docs.structurizr.com/server/documentation/diagrams

Embeds a diagram with parameters. The Markdown example sets the type to graph; the AsciiDoc example sets the perspective to Security.

```markdown
![](embed:MyDiagramKey{type=graph})
```

```asciidoc
image::embed:MyDiagramKey{perspective=Security}[]
```

--------------------------------

### Create a system context view

Source: https://docs.structurizr.com/java/getting-started

Creates a system context view and adds all software systems and people to it.

```java
ViewSet views = workspace.getViews();
SystemContextView contextView = views.createSystemContextView(softwareSystem, "SystemContext", "An example of a System Context diagram.");
contextView.addAllSoftwareSystems();
contextView.addAllPeople();
```

--------------------------------

### Start Structurizr with Java

Source: https://docs.structurizr.com/binaries

Runs the Structurizr .war file using Java. Requires Java 21. Replace <command> and [parameters] with the desired Structurizr command and arguments.

```bash
java -jar structurizr.war <command> [parameters] 

```

--------------------------------

### !adrs keyword syntax and example

Source: https://docs.structurizr.com/dsl/adrs

The first block shows the syntax for the !adrs keyword, which attaches Markdown/AsciiDoc ADRs to the parent context. The second block is an example usage where the path is a subdirectory relative to the parent file.

```plaintext
!adrs <path> [type|fqn]

```

```plaintext
!adrs subdirectory

```

--------------------------------

### Create components in different containers

Source: https://docs.structurizr.com/java/implied-relationships

Shows how to add a software system, two containers, and two components, one in each container. This setup is used to illustrate implied relationships.

```java
SoftwareSystem softwareSystem = model.addSoftwareSystem("Software System");
Container container1 = softwareSystem.addContainer("Container 1");
Component component1 = container1.addComponent("Component 1");

Container container2 = softwareSystem.addContainer("Container 2");
Component component2 = container2.addComponent("Component 2");
```

--------------------------------

### GET /api/workspace

Source: https://docs.structurizr.com/onpremises/admin-api

Retrieves metadata for all workspaces.

```APIDOC
## [GET] /api/workspace

### Description
Gets the metadata for all workspaces (i.e. ID, name, API key/secret pair, etc).

### Method
GET

### Endpoint
/api/workspace

### Parameters
#### Headers
- **X-Authorization** (string) - Required - The API key for authentication.

### Request Example
```
curl --header "X-Authorization: 1234567890" http://localhost:8080/api/workspace
```

### Response
#### Success Response (200)
- **workspaces** (array) - List of workspace metadata objects.

#### Response Example
(Not provided in source)

```

--------------------------------

### Run Structurizr server with Docker

Source: https://docs.structurizr.com/server/configuration

Starts the Structurizr server using the prebuilt Docker image, mounting the host directory PATH to the default data directory /usr/local/structurizr. The server listens on port 8080 by default.

```bash
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/structurizr server
```

--------------------------------

### Run Structurizr Lite Docker container

Source: https://docs.structurizr.com/lite/building

Starts a Docker container from the built image, mapping port 8080 and mounting the host directory `/path/to/dataDirectory` to `/usr/local/structurizr` inside the container.

```bash
docker run -it --rm -p 8080:8080 -v /path/to/dataDirectory:/usr/local/structurizr mytag
```

--------------------------------

### !include usage examples

Source: https://docs.structurizr.com/dsl/includes

Examples of !include usage: including a single local file (people.dsl), a file in a subdirectory (model/people.dsl), a directory (model), and a remote file via HTTPS URL. The included content is inlined in the order the files are discovered.

```plaintext
!include people.dsl
!include model/people.dsl
!include model
!include https://example.com/model/people.dsl

```

--------------------------------

### GET /api/workspace

Source: https://docs.structurizr.com/server/admin-api

Lists all workspaces on the Structurizr server.

```APIDOC
## GET /api/workspace

### Description
Lists all workspaces on the Structurizr server.

### Method
GET

### Endpoint
/api/workspace

### Parameters
#### Query Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **workspaces** (array) - List of workspace objects

#### Response Example
No response example provided in the source.

```

--------------------------------

### Run Structurizr server with Java

Source: https://docs.structurizr.com/server/configuration

Starts the Structurizr server directly from the Java .war file, specifying the data directory as a command line argument PATH.

```bash
java -jar structurizr.war server PATH
```

--------------------------------

### Run Docker container

Source: https://docs.structurizr.com/onpremises/building

Starts a Docker container from the built image, mapping port 8080 and mounting a data directory. Replace `/path/to/dataDirectory` with the actual path.

```bash
docker run -it --rm -p 8080:8080 -v /path/to/dataDirectory:/usr/local/structurizr mytag

```

--------------------------------

### GET /api/workspace/{workspaceId}/branch

Source: https://docs.structurizr.com/server/workspace-api

Retrieves the branches of a workspace.

```APIDOC
## GET /api/workspace/{workspaceId}/branch

### Description
Retrieves the branches of a workspace.

### Method
GET

### Endpoint
/api/workspace/{workspaceId}/branch

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace.

### Request Example
```
curl https://structurizr.example.com/api/workspace/123/branch
```

### Response
#### Success Response (200)
- **branches** (array) - List of branch names.

#### Response Example
```json
[
  "main",
  "feature"
]
```
```

--------------------------------

### Build Structurizr Lite from source

Source: https://docs.structurizr.com/lite/building

Clones the required repositories and builds Structurizr Lite from source. After a successful build, the file `structurizr-lite.war` is created in `structurizr-lite/build/libs`.

```bash
git clone https://github.com/structurizr/java.git structurizr-java
git clone --recursive https://github.com/structurizr/lite.git structurizr-lite
git clone https://github.com/structurizr/ui.git structurizr-ui
cd structurizr-java
./gradlew -Pversion=dev clean build publishToMavenLocal
cd ..
cd structurizr-lite
./ui.sh
./gradlew -PstructurizrVersion=dev clean build
```

--------------------------------

### push command

Source: https://docs.structurizr.com/push

Documentation for the push command, including its options and usage examples.

```APIDOC
## push

### Description
Pushes the specified DSL/JSON file to a Structurizr server. By default, it pulls the remote version of the workspace, merges diagram layout information from the remote version into the local version, and then pushes the local version.

### Command
`push`

### Options
- `-id` (string) - Required - The workspace ID.
- `-key` (string) - Required if authentication is enabled on the server - The workspace or admin API key.
- `-workspace` (string) - Optional - The path or URL to the workspace JSON/DSL file.
- `-image` (string) - Optional - The path to a PNG/JPG/SVG image file.
- `-url` (string) - Required - The Structurizr API URL.
- `-branch` (string) - Optional - Branch name.
- `-passphrase` (string) - Optional - The passphrase to use; only required if client-side encryption is enabled on the workspace.
- `-merge` (boolean) - Optional - Whether to merge layout information from the remote workspace; defaults to `true`.
- `-trim` (boolean) - Optional - Whether to trim the workspace before pushing; defaults to `false`.
- `-archive` (boolean) - Optional - Whether to store the previous version of the remote workspace; defaults to `true`.

### Notes
- One of `-workspace` and `-image` must be provided.
- You will need to use `-merge false` when pushing a workspace to a branch that doesn't exist on your Structurizr server.

### Examples

#### Push a new version of a workspace defined using the DSL
```
push -url https://structurizr.example.com/api -id 1234 -key 1234567890 -workspace workspace.dsl
```

#### Push an image to a workspace
```
push -url https://structurizr.example.com/api -id 1234 -key 1234567890 -image image.png
```
```

--------------------------------

### Create a workspace with the create command

Source: https://docs.structurizr.com/create

Creates a workspace on a Structurizr server. Requires the -url option with the API URL and -key with the admin API key if authentication is enabled. Optionally, -json can be used for JSON output.

```bash
create -url https://structurizr.example.com/api -key 1234567890
```

--------------------------------

### Dynamic view example with container and dynamic views

Source: https://docs.structurizr.com/dsl/cookbook/dynamic-view

Defines a model with a customer, an online book store containing a web application and a database, and relationships between them. Includes a container view and two dynamic views for the 'Request past orders' and 'Browse top 20 books' features, each with ordered relationships and auto layout.

```structurizr
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
        }
    }
    
}
```

--------------------------------

### GET /api/workspace/{workspaceId}

Source: https://docs.structurizr.com/server/workspace-api

Retrieves a workspace from the Structurizr server. This is a pull operation.

```APIDOC
## GET /api/workspace/{workspaceId}

### Description
Retrieves a workspace from the Structurizr server. This is a pull operation.

### Method
GET

### Endpoint
/api/workspace/{workspaceId}

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - The ID of the workspace to retrieve.

### Request Example
```
curl https://structurizr.example.com/api/workspace/123
```

### Response
#### Success Response (200)
- **workspace** (object) - The workspace JSON object.

#### Response Example
```json
{
  "id": 123,
  "name": "Example Workspace",
  "description": "..."
}
```
```

--------------------------------

### GET /api/workspace/{workspaceId}

Source: https://docs.structurizr.com/onpremises/workspace-api

Retrieves the workspace definition for a given workspace ID.

```APIDOC
## GET /api/workspace/{workspaceId}

### Description
Retrieves the workspace definition for the specified workspace ID.

### Method
GET

### Endpoint
/api/workspace/{workspaceId}

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - The unique identifier of the workspace to retrieve.

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **workspace definition** (object) - The JSON representation of the workspace.

#### Response Example
{
  "name": "My Workspace",
  "description": "A sample workspace"
}
```

--------------------------------

### Create a system catalog with software system definitions

Source: https://docs.structurizr.com/workspaces/enterprise

Defines a system catalog with three software systems (A, B, C) and their descriptions. Only software system definitions are included; internal details like containers and components are omitted. This file is intended to be published at an anonymous HTTPS URL for reuse across workspaces.

```structurizr
workspace {

    model {
        a = softwareSystem "A" {
            description "A description of software system A."
        }
        b = softwareSystem "B" {
            description "A description of software system B."
        }
        c = softwareSystem "C" {
            description "A description of software system C."
        }
    }
    
}

```

--------------------------------

### -server-read Get all workspaces from a Structurizr server

Source: https://docs.structurizr.com/ai/mcp

Retrieves all workspaces from a Structurizr server.

```APIDOC
## -server-read

### Description
Get all workspaces from a Structurizr server. Returns a collection of Structurizr workspaces.

### Parameters
- **Structurizr server URL** (string) - Required - The URL of the Structurizr server.
- **Admin API key** (string) - Optional - The admin API key for authentication. Not required if running the server with authentication disabled.

### Returns
- A collection of Structurizr workspaces.
```

--------------------------------

### create

Source: https://docs.structurizr.com/create

The `create` command creates a workspace on a Structurizr server. It requires the Structurizr API URL and optionally an admin API key if authentication is enabled. JSON output can be enabled with the `-json` flag.

```APIDOC
## create

### Description
Creates a workspace on a Structurizr server.

### Usage
```
create -url <url> -key <key> [-json]
```

### Options
- `-key` (string) - Required if authentication is enabled on the server. The admin API key.
- `-url` (string) - Required. The Structurizr API URL.
- `-json` (boolean) - Optional. Enables JSON output.

### Example
```
create -url https://structurizr.example.com/api -key 1234567890
```
```

--------------------------------

### Build Structurizr CLI from source

Source: https://docs.structurizr.com/cli/building

Clones the required repositories (java, cli, ui) and builds the Structurizr CLI from source. Requires git and Java 17+; the UI repo is needed for static site export. Run from a directory where you have write permissions.

```bash
git clone https://github.com/structurizr/java.git structurizr-java
git clone https://github.com/structurizr/cli.git structurizr-cli
git clone https://github.com/structurizr/ui.git structurizr-ui
cd structurizr-java
./gradlew -Pversion=dev clean build publishToMavenLocal
cd ..
cd structurizr-cli
./ui.sh
./gradlew -PstructurizrVersion=dev clean build getDeps buildZip
```

--------------------------------

### GET https://api.structurizr.com/workspace

Source: https://docs.structurizr.com/cloud/admin-api

Retrieves metadata for all workspaces associated with the authenticated user.

```APIDOC
## [GET] https://api.structurizr.com/workspace

### Description
Gets the metadata for all workspaces (i.e. ID, name, API key/secret pair, etc).

### Method
GET

### Endpoint
https://api.structurizr.com/workspace

### Authentication
- **X-Authorization** (string) - Required - The username and API key in the format `username:apiKey`.

### Request Example
```
curl --header "X-Authorization: user@example.com:1234567890" https://api.structurizr.com/workspace
```

### Response
#### Success Response (200)
- **workspaces** (array) - List of workspace metadata objects.

#### Response Example
```json
[
  {
    "id": 1234,
    "name": "My Workspace",
    "apiKey": "key",
    "apiSecret": "secret"
  }
]
```
```

--------------------------------

### pull

Source: https://docs.structurizr.com/cli/pull

Documentation for the Structurizr CLI pull command, including its options and an example invocation.

```APIDOC
## pull

### Description
Pulls content from a Structurizr workspace (cloud service or on-premises installation) as a JSON document. Creates a file named `structurizr-<id>-workspace.json` in the current directory.

### Method
CLI command

### Command
`structurizr.sh pull`

### Parameters
- **-id** (string) - Required - The workspace ID
- **-key** (string) - Required - The workspace API key
- **-secret** (string) - Required - The workspace API secret
- **-url** (string) - Optional - The Structurizr API URL (defaults to `https://api.structurizr.com`)
- **-branch** (string) - Optional - Branch name
- **-passphrase** (string) - Optional - The passphrase to use (only required if client-side encryption is enabled on the workspace)

### Example
```
./structurizr.sh pull -id 123456 -key 1a130d2b... -secret a9daaf3e...
```
```

--------------------------------

### Run Structurizr Lite with Docker and custom workspace path

Source: https://docs.structurizr.com/lite/usage

Starts Structurizr Lite in Docker, mounting the local data directory and setting STRUCTURIZR_WORKSPACE_PATH to select a subdirectory workspace. Use this when your workspace is in a subdirectory of the data directory.

```bash
docker run -it --rm -p 8080:8080 -v /Users/simon/structurizr:/usr/local/structurizr -e STRUCTURIZR_WORKSPACE_PATH=software-system-1 structurizr/lite
```
Tokens:
Raw