### Import documentation from a subdirectory

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/51-docs.md

Example of using a relative path to import documentation files.

```text
!docs subdirectory
```

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

### Run Structurizr Playground with Docker

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/01-playground/index.md

Starts the Structurizr playground using a pre-built Docker image. Assumes Docker is installed. The playground will be accessible on port 8080.

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

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

### Example Structurizr DSL Workspace

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

A minimal example of a Structurizr DSL workspace definition, including a model with a user and a system, and a system context view. This is typically placed in the mounted directory when using Docker.

```dsl
workspace {
    model {
        user = person "User"
        system = softwareSystem "System"
        user -> system "Uses"
    }
    views {
        systemContext system {
            include *
            autoLayout
        }
    }
}
```

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

### Define components and containers

Source: https://github.com/structurizr/structurizr.github.io/blob/main/java/implied-relationships.md

Initial setup of software system, containers, and components to demonstrate relationship modeling.

```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");
```

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

### Example Static Theme JSON Output

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ui/diagrams/themes.md

An example of a theme file in JSON format, typically generated from a Structurizr DSL workspace.

```json
{
  "name" : "Name",
  "description" : "Description",
  "elements" : [ { 
    "tag" : "Person",
    "shape" : "Person"
  } ]
}
```

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

### Example structurizr.roles File Format

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/08-authentication/03-file.md

Assign roles to users in the `structurizr.roles` file. Each line specifies the username and a comma-separated list of roles.

```plaintext
alice=role1
bob=role2
```

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

### Run Structurizr Lite container

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/02-installation.md

Start the container by mapping a local data directory to the container's internal path.

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

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

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

### Claude Desktop Configuration

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ai/mcp.md

Example configuration for Claude Desktop to connect to the MCP server.

```APIDOC
## Claude Desktop configuration

```
{
  ... 
  "mcpServers": {
    "structurizr-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
  ... 
}
```

(Claude Desktop doesn't permit `http` transport, so you'll need to use [mcp-remote](https://www.npmjs.com/package/mcp-remote) or similar that bridges stdio to a remote MCP server)
```

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

### Install Structurizr CLI with Scoop

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cli/installation.md

Installs the Structurizr CLI on Windows using the Scoop package manager. First, add the 'extras' bucket if you haven't already.

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

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

### Run Structurizr Docker Container

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/02-installation.md

Start the container by mapping a local data directory to the internal storage path.

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

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

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

### Run Structurizr Lite Docker Container

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/70-building.md

Start a Docker container from the built image, mapping port 8080 and mounting a volume for data persistence. Replace `/path/to/dataDirectory` with your desired host path.

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

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

### Install Structurizr CLI with Homebrew

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cli/installation.md

Installs the Structurizr CLI using the Homebrew package manager on macOS. Ensure Homebrew is installed first.

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

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

### Example structurizr.users File Format

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/08-authentication/03-file.md

Define users and their hashed passwords in the `structurizr.users` file. Each line represents a user in the format `username=hashed_password`.

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

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

### Start Structurizr Server with Docker

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/02-quickstart.md

Use these commands to pull the Structurizr Docker image and run it, mapping a local directory for data persistence. Replace PATH with your desired Structurizr data directory.

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

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

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

### Start Structurizr with Docker

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/02-local/01-quickstart.md

Commands to pull the Structurizr image and run it locally, mapping a host directory to the container's data volume.

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

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

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

### Example of Embedded Static Site Diagram

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/04-export/05-static.md

This is a live example demonstrating how a Structurizr diagram is embedded within a webpage using an iframe and the Structurizr embed script.

```html
<iframe src="https://c4model.com/example/index.html?diagram=SystemContext" style="width: 100%; max-height: 400px; border: none; overflow: hidden;" allow="fullscreen"></iframe>
<script type="text/javascript" src="https://c4model.com/example/js/structurizr-embed.js"></script>
```

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

### FreeIPA LDAP Configuration

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/05-authentication/ldap.md

Example configuration snippet for integrating with a FreeIPA server.

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

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

### Create a Structurizr workspace and model

Source: https://github.com/structurizr/structurizr.github.io/blob/main/java/getting-started.md

Initializes a new workspace and retrieves the model object to start defining software architecture elements.

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

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

### Structurizr DSL Include Examples

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/31-includes.md

Demonstrates various ways to use the `!include` keyword, including including single files, entire directories, and remote files from a URL. Ensure paths are relative to the parent file or are valid HTTPS URLs.

```structurizr-dsl
!include people.dsl
```

```structurizr-dsl
!include model/people.dsl
```

```structurizr-dsl
!include model
```

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

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

### Start Structurizr Lite with Docker

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/01-quickstart.md

Commands to pull and run the Structurizr Lite container, mapping a local directory to the container's data path.

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

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

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

### Clone Repositories and Build Structurizr

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/70-building.md

Clone the on-premises and UI repositories, then build the project using Gradle. Exclude integration tests if Docker is not installed.

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

```bash
./gradlew clean build -x integrationTest
```

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

### Define a basic Structurizr workspace

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/02-tutorial.md

Start by defining a workspace with a name and description. This serves as the root element for your architecture model and views.

```structurizr
workspace "Name" "Description" {
}
```

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

### Define theme styles in DSL

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/21-diagrams/04-themes.md

Example DSL workspace definition used as a source for theme generation.

```text
workspace "Name" "Description" {
    views {
        styles {
            element "Person" {
                shape person
            }
        }
    }
}
```

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

### Run Structurizr Docker Container

Source: https://github.com/structurizr/structurizr.github.io/blob/main/binaries.md

Starts a Structurizr Docker container, mounting the current directory for persistent storage. Replace `<command>` and `[parameters]` with specific Structurizr commands.

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

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

### Bulk create relationships using !elements

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/cookbook/bulk-operations-elements/index.md

Use the `!elements` keyword to select elements matching an expression and apply operations. This example creates relationships for all containers within software system 'A' to the 'Logging Service'.

```dsl
workspace  {

    model {
        loggingService = softwareSystem "Logging Service"

        a = softwareSystem "A" {
            container "App 1"
            container "App 2"
            container "App 3"

            !elements "element.parent==a" {
                this -> loggingService "Sends logs to"
            }
        }
    }

    views {
        container a "Containers" {
            include *
            autolayout
        }
    }
}
```

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

### Programmatically Add Elements to a View (Groovy)

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/cookbook/scripts/index.md

This example demonstrates how to define model elements and then use a Groovy script within a view definition to add specific software systems to the view based on their group and tags. Requires `workspace` and `view` objects.

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

}
```

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

### Start Structurizr Lite with a specific workspace path

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/03-usage.md

Use the STRUCTURIZR_WORKSPACE_PATH environment variable to target a subdirectory within 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
```

```bash
export STRUCTURIZR_WORKSPACE_PATH=software-system-1
java -jar structurizr-lite.war /Users/simon/structurizr
```

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

### Run Graphviz Locally for Layout (Groovy)

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/cookbook/scripts/index.md

This script applies Graphviz for automatic layout to the workspace. It requires Graphviz to be installed locally on the system where the script is executed. Requires the `workspace` object.

```groovy
!script groovy {
    new com.structurizr.graphviz.GraphvizAutomaticLayout().apply(workspace);
}
```

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

### Export Structurizr workspace to static site (DSL)

Source: https://github.com/structurizr/structurizr.github.io/blob/main/static/01-generating.md

Use this command to export a Structurizr workspace defined in DSL format to a static site. Ensure Graphviz is installed for automatic layout.

```bash
./structurizr.sh export -format static -workspace workspace.dsl -output static
```

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

### Run Structurizr Local with Docker on Custom Port

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Run Structurizr locally using Docker, mapping it to a custom port on your host machine. This example also demonstrates mounting the current directory for workspace files.

```bash
docker run -it --rm -p 9000:8080 \
    -v $(pwd)/workspace:/usr/local/structurizr \
    structurizr/structurizr local
```

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

### Pull and Run Structurizr On-Premises Docker Image

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/01-quickstart.md

Use these commands to download the Structurizr on-premises Docker image and start a container. Ensure you replace PATH with your actual Structurizr data directory path.

```bash
docker pull structurizr/onpremises
```

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

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

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

### Authenticate API Requests

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Example of performing an authenticated GET request using curl and HMAC headers.

```bash
curl -X GET \
    -H "X-Authorization: your-api-key:BASE64_HMAC_DIGEST" \
    -H "Nonce: 1699900000000" \
    "https://api.structurizr.com/workspace/12345"
```

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

### Build Docker Image

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/70-building.md

Navigate to the project directory and build a Docker image using the provided Dockerfile.

```bash
cd structurizr-onpremises
docker build . -t mytag
```

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

### Configure Structurizr Themes

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ai/mcp.md

Set the environment variable to point to the directory containing prebuilt themes.

```bash
-e STRUCTURIZR_THEMES=/usr/local/structurizr-themes
```

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

### Get Workspace

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cloud/21-workspace-api.md

Retrieves the JSON definition of a specific workspace.

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

### Description
Retrieves the JSON definition of a specific workspace.

### Method
GET

### Endpoint
`https://api.structurizr.com/workspace/{workspaceId}`

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

#### Query Parameters
None

#### Request Body
None

### Request Example
None

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

#### Response Example
```json
{
  "id": "1234",
  "name": "My Workspace",
  "version": "1.0",
  "workspace_elements": { ... },
  "workspace_relationships": { ... }
}
```
```

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

### GET /workspace

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cloud/22-admin-api.md

Retrieves metadata for all workspaces associated with the authenticated user.

```APIDOC
## GET /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

### Request Example
curl --header "X-Authorization: username:apiKey" https://api.structurizr.com/workspace
```

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

### Manage Workspaces with Java API

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Demonstrates initializing the client, retrieving, modifying, locking, and exporting workspaces.

```java
import com.structurizr.Workspace;
import com.structurizr.api.WorkspaceApiClient;
import com.structurizr.util.WorkspaceUtils;

public class WorkspaceOperations {
    public static void main(String[] args) throws Exception {
        // Initialize client for cloud service
        WorkspaceApiClient client = new WorkspaceApiClient(
            "https://api.structurizr.com",
            12345L,
            "your-api-key"
        );

        // For on-premises installation
        // WorkspaceApiClient client = new WorkspaceApiClient(
        //     "https://structurizr.example.com/api",
        //     12345L,
        //     "your-api-key"
        // );

        // Get workspace from server
        Workspace workspace = client.getWorkspace();
        System.out.println("Workspace: " + workspace.getName());
        System.out.println("Systems: " + workspace.getModel().getSoftwareSystems().size());

        // Modify workspace
        workspace.getModel().addPerson("New User", "Added programmatically");

        // Put workspace back (merges layout by default)
        client.putWorkspace(workspace);

        // Workspace locking
        boolean locked = client.lockWorkspace();
        if (locked) {
            try {
                // Make changes while locked
                workspace = client.getWorkspace();
                // ... modifications ...
                client.putWorkspace(workspace);
            } finally {
                client.unlockWorkspace();
            }
        }

        // Disable automatic archiving
        client.setWorkspaceArchiveLocation(null);

        // Export to different formats
        WorkspaceUtils.saveWorkspaceToJson(workspace, new java.io.File("backup.json"));
    }
}
```

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

### Initialize WorkspaceApiClient

Source: https://github.com/structurizr/structurizr.github.io/blob/main/java/workspace-api-client.md

Create a new instance of the client using the server URL, workspace ID, and API key.

```java
WorkspaceApiClient client = new WorkspaceApiClient("https://structurizr.example.com", 1234, "apikey");
```

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

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

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/11-workspace-api.md

Retrieves the workspace definition for the specified 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.
```

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

### Get Current View Key

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/21-diagrams/31-scripting.md

Retrieves the key of the currently displayed view.

```javascript
structurizr.scripting.getViewKey()
```

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

### Running the MCP Server

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ai/mcp.md

Instructions for running the MCP server using Docker or building from source.

```APIDOC
## Running

A prebuilt Docker image is available on Docker Hub:

```
docker pull structurizr/mcp
docker run -it --rm -p 3000:3000 -e PORT=3000 structurizr/mcp <parameters>
```

The following parameters are supported:

- `-dsl`: Enable DSL tools.
- `-server-create`: Enable Structurizr [server](/server) create tools.
- `-server-read`: Enable Structurizr [server](/server) read tools.
- `-server-update`: Enable Structurizr [server](/server) update tools.
- `-server-delete`: Enable Structurizr [server](/server) delete tools.
- `-plantuml`: Enable PlantUML exporter.
- `-mermaid`: Enable Mermaid exporter.

### Themes

The [prebuilt themes](/server/diagrams/themes) are included in the Docker image, and can be "installed" via an environment variable:

```
-e STRUCTURIZR_THEMES=/usr/local/structurizr-themes
```

## Building and running from source

Prerequisites:

- Java 21

To build:

```
git clone https://github.com/structurizr/structurizr.git
cd structurizr
./mvnw -Dmaven.test.skip=true package -am -pl structurizr-mcp
```

If successful, there will be a `structurizr-mcp-1.0.0.war` file in `structurizr-mcp/target`.

```
java -jar structurizr-mcp/target/structurizr-mcp-1.0.0.war <parameters>
```

To change the port number:

```
java -Dserver.port=3000 -jar structurizr-mcp/target/structurizr-mcp-1.0.0.war <parameters>
```

To create a Docker image:

```
docker build . -f structurizr-mcp/Dockerfiles/eclipse-temurin-alpine -t structurizr-mcp
```
```

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

### Get workspace without authentication

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/51-workspace-api.md

Retrieve workspace data from a server where authentication is disabled.

```bash
curl https://structurizr.example.com/api/workspace/123
```

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

### Get All Views

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/21-diagrams/31-scripting.md

Retrieves an array of objects, where each object represents a view in the software architecture model.

```javascript
structurizr.scripting.getViews()
```

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

### Get All Workspaces

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/12-admin-api.md

Retrieves metadata for all existing workspaces, including their IDs, names, and API key/secret pairs.

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

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

### Response
#### Success Response (200)
- **workspaces** (array) - A list of workspace objects.
  - **id** (integer) - The unique identifier for the workspace.
  - **name** (string) - The name of the workspace.
  - **apiKey** (string) - The API key for the workspace.
  - **apiSecret** (string) - The API secret for the workspace.

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

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

### Get workspace with authentication

Source: https://github.com/structurizr/structurizr.github.io/blob/main/commands/03-server/51-workspace-api.md

Retrieve workspace data using an API key via the X-Authorization header.

```bash
curl https://structurizr.example.com/api/workspace/123 -H "X-Authorization: 1234567890"
```

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

### Clone and Build Structurizr Java, Lite, and UI

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/70-building.md

Clone the necessary Structurizr repositories and build the Java project locally. This sets up the dependencies for building Structurizr Lite.

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

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

### Configure Distributed Redis Caching

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/08-data-storage.md

Required for multi-server installations to ensure consistent cache state across nodes.

```properties
structurizr.cache=redis
structurizr.redis.host=localhost
structurizr.redis.port=6379
structurizr.redis.database=0
structurizr.redis.password=
```

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

### Build Docker Image from Source

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ai/mcp.md

Create a custom Docker image using the provided Dockerfile.

```bash
docker build . -f structurizr-mcp/Dockerfiles/eclipse-temurin-alpine -t structurizr-mcp
```

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

### Enable Local In-Memory Caching

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/08-data-storage.md

Use this setting for single-server installations to improve performance by caching workspace metadata.

```properties
structurizr.cache=local
```

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

### Global Identifier Scope Failure

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/05-identifiers.md

This example demonstrates an error that occurs when duplicate identifiers are used in a globally scoped model.

```structurizr
workspace {

    model {
        softwareSystem1 = softwareSystem "Software System 1" {
            api = container "API"
        }

        softwareSystem2 = softwareSystem "Software System 2" {
            api = container "API"
        }
    }
}
```

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

### Get workspace content

Source: https://github.com/structurizr/structurizr.github.io/blob/main/java/workspace-api-client.md

Retrieve the content of a remote workspace. By default, this operation archives a JSON copy to the working directory.

```java
Workspace workspace = client.getWorkspace();
```

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

### Define Relationships in Structurizr DSL

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/02-tutorial.md

Examples showing explicit relationship definitions and the reduction of redundancy using implied relationships.

```Structurizr DSL
        u -> ss "Uses"
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
```

```Structurizr DSL
        u -> ss.wa "Uses"
        ss.wa -> ss.db "Reads from and writes to"
```

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

### Push Workspace via CLI

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Deploy a DSL workspace to a Structurizr server using various authentication and configuration options.

```bash
# Push to Structurizr cloud
./structurizr.sh push \
    -id 12345 \
    -key "your-api-key" \
    -secret "your-api-secret" \
    -workspace workspace.dsl

# Push to on-premises server
./structurizr.sh push \
    -url "https://structurizr.example.com/api" \
    -id 12345 \
    -key "your-api-key" \
    -secret "your-api-secret" \
    -workspace workspace.dsl

# Push with client-side encryption
./structurizr.sh push \
    -id 12345 \
    -key "your-api-key" \
    -secret "your-api-secret" \
    -workspace workspace.dsl \
    -passphrase "encryption-passphrase"

# Push to a specific branch
./structurizr.sh push \
    -id 12345 \
    -key "your-api-key" \
    -secret "your-api-secret" \
    -workspace workspace.dsl \
    -branch "feature/new-architecture"
```

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

### Import documentation syntax

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/51-docs.md

Basic syntax for the !docs keyword to attach documentation to a context.

```text
!docs <path> [fully qualified class name]
```

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

### Build Structurizr MCP from Source

Source: https://github.com/structurizr/structurizr.github.io/blob/main/ai/mcp.md

Clone the repository and build the MCP module using Maven.

```bash
git clone https://github.com/structurizr/structurizr.git
cd structurizr
./mvnw -Dmaven.test.skip=true package -am -pl structurizr-mcp
```

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

### Get All Workspaces using curl

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cloud/22-admin-api.md

Retrieves metadata for all workspaces. Ensure your X-Authorization header is correctly formatted with your username and API key.

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

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

### Define a system context view

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/02-tutorial.md

Configure a system context view to visualize the software system and its immediate environment. Use 'include *' to automatically include related elements.

```structurizr
workspace "Name" "Description" {

    model {
        u = person "User"
        ss = softwareSystem "Software System"

        u -> ss "Uses"
    }

    views {
        systemContext ss "Diagram1" {
            include *
        }
    }
    
}
```

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

### Run Structurizr Local with Docker

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Pull and run the Structurizr Docker image to set up a local instance for development. Mount your workspace directory to access DSL files and view the service at http://localhost:8080.

```bash
docker pull structurizr/structurizr
docker run -it --rm -p 8080:8080 \
    -v /path/to/workspace:/usr/local/structurizr \
    structurizr/structurizr local
```

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

### Run the Structurizr application

Source: https://github.com/structurizr/structurizr.github.io/blob/main/building.md

Executes the built WAR file using the Java runtime.

```bash
java -jar structurizr-application/target/structurizr-1.0.0.war
```

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

### Clone Structurizr for Java Repository

Source: https://github.com/structurizr/structurizr.github.io/blob/main/java/building.md

Clone the official Structurizr for Java repository using Git. Ensure you have Git and Java 17+ installed.

```bash
git clone https://github.com/structurizr/java.git structurizr-java
cd structurizr-java
./gradlew
```

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

### Microsoft Active Directory LDAP Configuration

Source: https://github.com/structurizr/structurizr.github.io/blob/main/onpremises/05-authentication/ldap.md

Example configuration for Microsoft Active Directory, requiring updates to the search base, URL, and credentials.

```xml
<beans:bean id="ldapAuthProvider" class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider">
    <beans:constructor-arg>
        <beans:bean class="org.springframework.security.ldap.authentication.BindAuthenticator">
            <beans:constructor-arg ref="contextSource"/>
            <beans:property name="userSearch" ref="userSearch"/>
        </beans:bean>
    </beans:constructor-arg>
    <beans:constructor-arg>
        <beans:bean class="org.springframework.security.ldap.userdetails.DefaultLdapAuthoritiesPopulator">
            <beans:constructor-arg index="0" ref="contextSource"/>
            <beans:constructor-arg index="1" value="DC=mycompany,DC=local"/>
            <beans:property name="groupSearchFilter" value="(member={0})"/>
            <beans:property name="ignorePartialResultException" value="true"/>
            <beans:property name="searchSubtree" value="true"/>
        </beans:bean>
    </beans:constructor-arg>
</beans:bean>

<beans:bean id="userSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
    <beans:constructor-arg index="0" value="DC=mycompany,DC=local"/>
    <beans:constructor-arg index="1" value="(sAMAccountName={0})"/>
    <beans:constructor-arg index="2" ref="contextSource" />
</beans:bean>

<beans:bean id="contextSource" class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">
    <beans:constructor-arg value="ldap://127.0.0.1:389"/>
    <beans:property name="userDn" value="MYCOMPANY\Administrator"/>
    <beans:property name="password" value="password"/>
</beans:bean>

<authentication-manager>
    <authentication-provider ref="ldapAuthProvider" />
</authentication-manager>
```

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

### Build a Docker image

Source: https://github.com/structurizr/structurizr.github.io/blob/main/building.md

Creates a Docker image using the specified Dockerfile after the project has been built.

```bash
docker build . -f structurizr-application/Dockerfiles/eclipse-temurin-alpine -t structurizr
```

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

### Run Structurizr Lite Spring Boot application

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/02-installation.md

Execute the WAR file using Java, specifying the path to the data directory.

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

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

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

### Define implied relationships in DSL

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/07-implied-relationships.md

Example showing a relationship between a person and a container, which results in an implied relationship between the person and the parent software system.

```text
workspace {

    model {
        u = person "User"
        s = softwareSystem "Software System" {
            webapp = container "Web Application"
        }

        u -> webapp "Uses"
    }

    views {
        systemContext s {
            include *
            autoLayout lr
        }
    }
    
}
```

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

### Run Structurizr Lite JAR

Source: https://github.com/structurizr/structurizr.github.io/blob/main/lite/70-building.md

Execute the built Structurizr Lite WAR file using Java. Ensure you replace `/path/to/workspace` with the actual path to your workspace file.

```bash
java -jar build/libs/structurizr-lite.war /path/to/workspace
```

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

### Define a software system instance

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/71-language.md

Defines an instance of a software system deployed on a parent deployment node.

```text
softwareSystemInstance <identifier> [deploymentGroups] [tags] {
    ...
}
```

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

### Pull Structurizr Docker Image

Source: https://github.com/structurizr/structurizr.github.io/blob/main/binaries.md

Use this command to download the latest Structurizr Docker image from Docker Hub. Ensure Docker is installed and configured.

```bash
docker pull structurizr/structurizr
```

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

### Create Workspace using curl

Source: https://github.com/structurizr/structurizr.github.io/blob/main/cloud/22-admin-api.md

Creates a new workspace. Use the POST method and include your authentication credentials in the X-Authorization header.

```bash
curl -X POST --header "X-Authorization: user@example.com:1234567890" https://api.structurizr.com/workspace
```

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

### Single-line Comment using Hash

Source: https://github.com/structurizr/structurizr.github.io/blob/main/dsl/03-basics.md

Define single-line comments by starting the line with a hash symbol (`#`). This is a common convention for comments in many scripting languages.

```structurizr
# single line comment
```

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

### Build Structurizr with Maven

Source: https://github.com/structurizr/structurizr.github.io/blob/main/building.md

Clones the repository and builds the project while excluding integration tests that require Docker.

```bash
git clone https://github.com/structurizr/structurizr.git
cd structurizr
./mvnw -DexcludedGroups=IntegrationTest package
```

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

### Java API - Workspace Operations

Source: https://context7.com/structurizr/structurizr.github.io/llms.txt

Use the WorkspaceApiClient to interact with Structurizr server workspaces. This includes getting, modifying, and putting workspaces, as well as locking and unlocking them.

```APIDOC
## Java API - Workspace Operations

Use the WorkspaceApiClient to interact with Structurizr server workspaces.

```java
import com.structurizr.Workspace;
import com.structurizr.api.WorkspaceApiClient;
import com.structurizr.util.WorkspaceUtils;

public class WorkspaceOperations {
    public static void main(String[] args) throws Exception {
        // Initialize client for cloud service
        WorkspaceApiClient client = new WorkspaceApiClient(
            "https://api.structurizr.com",
            12345L,
            "your-api-key"
        );

        // For on-premises installation
        // WorkspaceApiClient client = new WorkspaceApiClient(
        //     "https://structurizr.example.com/api",
        //     12345L,
        //     "your-api-key"
        // );

        // Get workspace from server
        Workspace workspace = client.getWorkspace();
        System.out.println("Workspace: " + workspace.getName());
        System.out.println("Systems: " + workspace.getModel().getSoftwareSystems().size());

        // Modify workspace
        workspace.getModel().addPerson("New User", "Added programmatically");

        // Put workspace back (merges layout by default)
        client.putWorkspace(workspace);

        // Workspace locking
        boolean locked = client.lockWorkspace();
        if (locked) {
            try {
                // Make changes while locked
                workspace = client.getWorkspace();
                // ... modifications ...
                client.putWorkspace(workspace);
            } finally {
                client.unlockWorkspace();
            }
        }

        // Disable automatic archiving
        client.setWorkspaceArchiveLocation(null);

        // Export to different formats
        WorkspaceUtils.saveWorkspaceToJson(workspace, new java.io.File("backup.json"));
    }
}
```
```