Structurizr On-Premises

https://github.com/structurizr/onpremises
Admin
Structurizr On-Premises is a self-hosted installation of the Structurizr platform for creating and...
Tokens:10,793
Snippets:60
Trust Score:9.5
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create, Get, and Update Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Demonstrates creating a new workspace, retrieving its metadata and JSON content, and updating it. Requires an authenticated user.

```java
long workspaceId = workspaceComponent.createWorkspace(user);
```

```java
WorkspaceMetaData metadata = workspaceComponent.getWorkspaceMetaData(workspaceId);
System.out.println("Name: " + metadata.getName());
System.out.println("API Key: " + metadata.getApiKey());
System.out.println("API Secret: " + metadata.getApiSecret());
System.out.println("Is Locked: " + metadata.isLocked());
System.out.println("Last Modified: " + metadata.getLastModifiedDate());
```

```java
String json = workspaceComponent.getWorkspace(workspaceId, "", null);
String branchJson = workspaceComponent.getWorkspace(workspaceId, "feature-branch", null);
String versionedJson = workspaceComponent.getWorkspace(workspaceId, "", "20240115120000000");
```

```java
workspaceComponent.putWorkspace(workspaceId, "", workspaceJsonString);
workspaceComponent.putWorkspace(workspaceId, "feature-branch", branchJsonString);
```

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

### Structurizr Core Configuration Properties

Source: https://context7.com/structurizr/onpremises/llms.txt

Example structurizr.properties file showing core configuration settings for URL, data directory, API keys, storage, authentication, and search.

```properties
# structurizr.properties - Core configuration file

# Base URL for the installation
structurizr.url=https://structurizr.example.com

# Data directory path
structurizr.datadirectory=/var/structurizr/data

# Admin API key (BCrypt hashed)
structurizr.apikey=$2a$10$...hashed-api-key...

# Admin users/roles (comma-separated)
structurizr.admin=admin@example.com,architects

# Maximum workspace versions to retain (default: 30)
structurizr.maxworkspaceversions=30

# Data storage: file, aws-s3, or azure-blob
structurizr.data=file

# AWS S3 configuration (when structurizr.data=aws-s3)
structurizr.aws-s3.accesskeyid=AKIAIOSFODNN7EXAMPLE
structurizr.aws-s3.secretaccesskey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
structurizr.aws-s3.region=us-east-1
structurizr.aws-s3.bucketname=structurizr-workspaces

# Azure Blob Storage configuration (when structurizr.data=azure-blob)
structurizr.azure-blob.accountname=structurizraccount
structurizr.azure-blob.accesskey=your-access-key
structurizr.azure-blob.containername=workspaces

# Authentication: file or saml
structurizr.authentication=file

# Session storage: local or redis
structurizr.session=local

# Search implementation: none, lucene, or elasticsearch
structurizr.search=lucene

# Elasticsearch configuration (when structurizr.search=elasticsearch)
structurizr.elasticsearch.protocol=https
structurizr.elasticsearch.host=elasticsearch.example.com
structurizr.elasticsearch.port=9200
structurizr.elasticsearch.username=elastic
structurizr.elasticsearch.password=secret

# Redis configuration (for session/cache)
structurizr.redis.host=redis.example.com
structurizr.redis.port=6379
structurizr.redis.password=redis-password
structurizr.redis.database=0

# Feature toggles
structurizr.feature.ui.dsleditor=true
structurizr.feature.ui.workspaceusers=true
structurizr.feature.ui.workspacesettings=true
structurizr.feature.workspace.archiving=true
structurizr.feature.workspace.branches=true
structurizr.feature.diagramreviews=true

# Network settings
structurizr.internetconnection=true
structurizr.network.timeout=60000
structurizr.network.urls.allowed=https://.*
```

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

### Structurizr SAML Authentication Configuration

Source: https://context7.com/structurizr/onpremises/llms.txt

Example structurizr.properties snippet for configuring SAML authentication, including registration ID, entity ID, and IdP metadata source.

```properties
# structurizr.properties - SAML configuration

structurizr.authentication=saml

# SAML registration ID (identifier for the SP)
structurizr.saml.registrationid=structurizr

# Entity ID for Service Provider
structurizr.saml.entityid=https://structurizr.example.com/saml/metadata

# IdP metadata URL or file path
structurizr.saml.metadata=https://idp.example.com/metadata.xml
```

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

### Get Workspace Versions and Branches

Source: https://context7.com/structurizr/onpremises/llms.txt

Retrieves a list of all versioned states and branches for a given workspace.

```java
List<WorkspaceVersion> versions = workspaceComponent.getWorkspaceVersions(workspaceId, "");
for (WorkspaceVersion version : versions) {
    System.out.println("Version: " + version.getVersionId() + " at " + version.getLastModifiedDate());
}
```

```java
List<WorkspaceBranch> branches = workspaceComponent.getWorkspaceBranches(workspaceId);
```

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

### Dockerfile for Structurizr On-Premises

Source: https://context7.com/structurizr/onpremises/llms.txt

This Dockerfile sets up Structurizr On-Premises with Tomcat 10.1 and JRE 21, including Graphviz for diagram layout. It configures the Tomcat port and installs necessary dependencies.

```dockerfile
# Dockerfile included in the project
FROM tomcat:10.1.41-jre21-temurin-noble
ENV PORT=8080

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends graphviz

RUN sed -i 's/port="8080"/port="${http.port}" maxPostSize="10485760"/' conf/server.xml \
  && echo 'export CATALINA_OPTS="-Xms512M -Xmx512M -Dhttp.port=$PORT"' > bin/setenv.sh

ADD build/libs/structurizr-onpremises.war /usr/local/tomcat/webapps/ROOT.war

EXPOSE ${PORT}

CMD ["catalina.sh", "run"]
```

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

### Get Structurizr Workspace JSON

Source: https://context7.com/structurizr/onpremises/llms.txt

Retrieves workspace JSON data using HMAC-SHA256 authentication. Ensure correct headers like Authorization, Nonce, and Content-MD5 are included. The Content-MD5 header should be a base64 encoded MD5 hash of the request body (empty for GET requests).

```bash
# Get workspace JSON
# Required headers: Authorization, Nonce, Content-MD5
# Authorization format: {apiKey}:{base64EncodedHmac}

WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)
CONTENT_MD5="d41d8cd98f00b204e9800998ecf8427e"  # MD5 of empty string

# Generate HMAC content: METHOD\nPATH\nCONTENT_MD5\nCONTENT_TYPE\nNONCE
HMAC_CONTENT="GET
/api/workspace/${WORKSPACE_ID}
${CONTENT_MD5}

${NONCE}
"

# Generate HMAC-SHA256 signature
HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X GET "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: $(echo -n ${CONTENT_MD5} | base64)"
```

```bash
# Get specific version
curl -X GET "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}?version=20240115120000000" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: $(echo -n ${CONTENT_MD5} | base64)"
```

```bash
# Get workspace from a branch
curl -X GET "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/branch/feature-branch" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: $(echo -n ${CONTENT_MD5} | base64)"
```

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

### Implement Workspace Event Listener in Java

Source: https://context7.com/structurizr/onpremises/llms.txt

Implement the WorkspaceEventListener interface to execute custom code before workspace save operations. This example shows how to access workspace metadata and perform actions like sending notifications or creating backups.

```java
package com.example.structurizr.plugins;

import com.structurizr.onpremises.component.workspace.WorkspaceEvent;
import com.structurizr.onpremises.component.workspace.WorkspaceEventListener;
import com.structurizr.onpremises.component.workspace.WorkspaceProperties;

public class AuditWorkspaceEventListener implements WorkspaceEventListener {

    @Override
    public void beforeSave(WorkspaceEvent event) {
        WorkspaceProperties workspace = event.getWorkspaceProperties();

        // Access workspace metadata
        long workspaceId = workspace.getId();
        String name = workspace.getName();
        String description = workspace.getDescription();

        // Log audit information
        System.out.println("Workspace " + workspaceId + " (" + name + ") is being saved");

        // Perform validation, notifications, backups, etc.
        sendNotification("Workspace updated: " + name);
        createBackup(workspaceId);
    }

    private void sendNotification(String message) {
        // Custom notification logic
    }

    private void createBackup(long workspaceId) {
        // Custom backup logic
    }
}
```

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

### Workspace API - Get Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Retrieves workspace JSON data. Requires HMAC-SHA256 signed requests with API key and secret.

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

### Description
Retrieves the JSON representation of a workspace, including its model, views, and documentation.

### Method
GET

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

### Query Parameters
- **version** (string) - Optional - Specifies a particular version of the workspace to retrieve (e.g., "20240115120000000").

### Headers
- **Authorization** (string) - Required - HMAC-SHA256 signature in the format "{apiKey}:{base64EncodedHmac}".
- **Nonce** (string) - Required - A unique, monotonically increasing number (e.g., Unix timestamp).
- **Content-MD5** (string) - Required - Base64 encoded MD5 hash of the request body (empty for GET requests).

### Request Example
```bash
WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)
CONTENT_MD5="d41d8cd98f00b204e9800998ecf8427e"

HMAC_CONTENT="GET\n/api/workspace/${WORKSPACE_ID}\n${CONTENT_MD5}\n\n${NONCE}"
HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X GET "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: $(echo -n ${CONTENT_MD5} | base64)"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the workspace.
- **name** (string) - The name of the workspace.
- **description** (string) - A description of the workspace.
- **model** (object) - The architecture model.
- **views** (object) - The architecture views.

#### Response Example
```json
{
  "id": 1,
  "name": "Example Workspace",
  "description": "Workspace description",
  "model": { ... },
  "views": { ... }
}
```

### Branch Specific Retrieval
To retrieve a workspace from a specific branch:

```bash
curl -X GET "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/branch/feature-branch" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: $(echo -n ${CONTENT_MD5} | base64)"
```
```

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

### Docker Compose for Structurizr with Redis and Elasticsearch

Source: https://context7.com/structurizr/onpremises/llms.txt

A Docker Compose configuration to deploy Structurizr On-Premises along with Redis and Elasticsearch services. This setup is useful for development and testing environments requiring these dependencies.

```yaml
version: '3.8'
services:
  structurizr:
    build: ./structurizr-onpremises
    ports:
      - "8080:8080"
    volumes:
      - ./data:/usr/local/structurizr
    environment:
      - CATALINA_OPTS=-Xms1G -Xmx2G

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  elasticsearch:
    image: elasticsearch:7.17.10
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
```

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

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

Source: https://context7.com/structurizr/onpremises/llms.txt

Commands to build the Structurizr On-Premises WAR file, build the Docker image, and run the container with local file storage. Ensure the volume mapping and environment variables are correctly set for your environment.

```bash
# Build the WAR file
./gradlew clean build

# Build Docker image
docker build -t structurizr-onpremises ./structurizr-onpremises

# Run with local file storage
docker run -d \
  -p 8080:8080 \
  -v /path/to/data:/usr/local/structurizr \
  -e STRUCTURIZR_DATA_DIRECTORY=/usr/local/structurizr \
  structurizr-onpremises
```

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

### Create a New Structurizr Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Use this command to create a new workspace via the Admin API. An admin API key is required.

```bash
curl -X POST "https://structurizr.example.com/api/workspace" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

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

### List All Structurizr Workspaces

Source: https://context7.com/structurizr/onpremises/llms.txt

This command lists all available workspaces using the Admin API. Requires an admin API key.

```bash
ADMIN_API_KEY="admin-secret-key"

curl -X GET "https://structurizr.example.com/api/workspace" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

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

### Index and Search Workspace Content

Source: https://context7.com/structurizr/onpremises/llms.txt

Demonstrates indexing a workspace and performing full-text searches across different content types. Requires the search component to be enabled.

```java
if (searchComponent.isEnabled()) {
    Workspace workspace = loadWorkspace();
    searchComponent.index(workspace);

    Set<Long> accessibleWorkspaceIds = Set.of(1L, 2L, 3L);

    List<SearchResult> results = searchComponent.search("authentication", null, accessibleWorkspaceIds);

    List<SearchResult> diagramResults = searchComponent.search("login", "diagram", accessibleWorkspaceIds);
    List<SearchResult> docResults = searchComponent.search("API design", "documentation", accessibleWorkspaceIds);
    List<SearchResult> adrResults = searchComponent.search("microservices", "decision", accessibleWorkspaceIds);

    for (SearchResult result : results) {
        System.out.println("Workspace: " + result.getWorkspaceId());
        System.out.println("URL: " + result.getUrl());
        System.out.println("Name: " + result.getName());
        System.out.println("Description: " + result.getDescription());
        System.out.println("Type: " + result.getType());
    }

    searchComponent.delete(workspaceId);
}
```

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

### Configuration Properties

Source: https://context7.com/structurizr/onpremises/llms.txt

Configuration settings for Structurizr, managed via the `structurizr.properties` file.

```APIDOC
# Configuration Properties

## `structurizr.properties` File

The server configuration is managed through a `structurizr.properties` file placed in the data directory. This file controls storage backends, authentication methods, search implementation, and feature toggles.

### Core Settings

- **structurizr.url**: Base URL for the installation (e.g., `https://structurizr.example.com`).
- **structurizr.datadirectory**: Path to the data directory (e.g., `/var/structurizr/data`).
- **structurizr.apikey**: Admin API key (BCrypt hashed).
- **structurizr.admin**: Comma-separated list of admin users/roles (e.g., `admin@example.com,architects`).
- **structurizr.maxworkspaceversions**: Maximum workspace versions to retain (default: 30).
- **structurizr.data**: Data storage backend (`file`, `aws-s3`, or `azure-blob`).
- **structurizr.authentication**: Authentication method (`file` or `saml`).
- **structurizr.session**: Session storage (`local` or `redis`).
- **structurizr.search**: Search implementation (`none`, `lucene`, or `elasticsearch`).
- **structurizr.internetconnection**: Boolean indicating if internet connection is enabled (default: `true`).
- **structurizr.network.timeout**: Network timeout in milliseconds (default: 60000).
- **structurizr.network.urls.allowed**: Regular expression for allowed network URLs (e.g., `https://.*`).

### AWS S3 Configuration (when `structurizr.data=aws-s3`)

- **structurizr.aws-s3.accesskeyid**: AWS Access Key ID.
- **structurizr.aws-s3.secretaccesskey**: AWS Secret Access Key.
- **structurizr.aws-s3.region**: AWS region (e.g., `us-east-1`).
- **structurizr.aws-s3.bucketname**: S3 bucket name.

### Azure Blob Storage Configuration (when `structurizr.data=azure-blob`)

- **structurizr.azure-blob.accountname**: Azure storage account name.
- **structurizr.azure-blob.accesskey**: Azure storage account access key.
- **structurizr.azure-blob.containername**: Azure blob container name.

### Elasticsearch Configuration (when `structurizr.search=elasticsearch`)

- **structurizr.elasticsearch.protocol**: Elasticsearch protocol (`http` or `https`).
- **structurizr.elasticsearch.host**: Elasticsearch host address.
- **structurizr.elasticsearch.port**: Elasticsearch port (e.g., 9200).
- **structurizr.elasticsearch.username**: Elasticsearch username.
- **structurizr.elasticsearch.password**: Elasticsearch password.

### Redis Configuration (for session/cache)

- **structurizr.redis.host**: Redis host address.
- **structurizr.redis.port**: Redis port (e.g., 6379).
- **structurizr.redis.password**: Redis password.
- **structurizr.redis.database**: Redis database number (default: 0).

### Feature Toggles

- **structurizr.feature.ui.dsleditor**: Enable/disable DSL editor in UI.
- **structurizr.feature.ui.workspaceusers**: Enable/disable workspace users management in UI.
- **structurizr.feature.ui.workspacesettings**: Enable/disable workspace settings in UI.
- **structurizr.feature.workspace.archiving**: Enable/disable workspace archiving.
- **structurizr.feature.workspace.branches**: Enable/disable workspace branching.
- **structurizr.feature.diagramreviews**: Enable/disable diagram reviews.

### SAML Authentication Configuration

When `structurizr.authentication=saml`:

- **structurizr.saml.registrationid**: Service Provider (SP) registration ID (e.g., `structurizr`).
- **structurizr.saml.entityid**: Entity ID for the Service Provider (e.g., `https://structurizr.example.com/saml/metadata`).
- **structurizr.saml.metadata**: URL or file path to the Identity Provider (IdP) metadata (e.g., `https://idp.example.com/metadata.xml`).
```

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

### Lock and Unlock Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Shows how to lock a workspace to prevent concurrent modifications and how to unlock it. Requires user and client information for locking.

```java
boolean locked = workspaceComponent.lockWorkspace(workspaceId, "user@example.com", "my-client/1.0");
```

```java
boolean unlocked = workspaceComponent.unlockWorkspace(workspaceId);
```

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

### WorkspaceComponent Interface

Source: https://context7.com/structurizr/onpremises/llms.txt

Provides programmatic access to workspace operations, abstracting storage backends and offering consistent workspace management.

```APIDOC
## WorkspaceComponent Interface

### Description
The WorkspaceComponent interface provides programmatic access to workspace operations. It abstracts storage backends and provides consistent workspace management functionality.

### Methods
- `createWorkspace(User user)`: Creates a new workspace.
- `getWorkspaceMetaData(long workspaceId)`: Retrieves metadata for a given workspace.
- `getWorkspace(long workspaceId, String branch, String version)`: Retrieves the workspace JSON, optionally filtered by branch and version.
- `putWorkspace(long workspaceId, String branch, String workspaceJsonString)`: Updates the workspace JSON for a given branch.
- `lockWorkspace(long workspaceId, String user, String client)`: Locks a workspace.
- `unlockWorkspace(long workspaceId)`: Unlocks a workspace.
- `getWorkspaceVersions(long workspaceId, String branch)`: Retrieves a list of available versions for a workspace.
- `getWorkspaceBranches(long workspaceId)`: Retrieves a list of available branches for a workspace.
- `makeWorkspacePublic(long workspaceId)`: Makes a workspace public.
- `makeWorkspacePrivate(long workspaceId)`: Makes a workspace private.
- `shareWorkspace(long workspaceId)`: Generates a shareable link for the workspace.
- `unshareWorkspace(long workspaceId)`: Removes the shareable link for the workspace.
- `deleteWorkspace(long workspaceId)`: Deletes a workspace.

### Request Example (Create Workspace)
```java
// Inject the component via Spring
@Autowired
private WorkspaceComponent workspaceComponent;

// Create a new workspace
long workspaceId = workspaceComponent.createWorkspace(user);
```

### Response Example (Get Workspace Metadata)
```java
// Get workspace metadata
WorkspaceMetaData metadata = workspaceComponent.getWorkspaceMetaData(workspaceId);
System.out.println("Name: " + metadata.getName());
System.out.println("API Key: " + metadata.getApiKey());
System.out.println("API Secret: " + metadata.getApiSecret());
System.out.println("Is Locked: " + metadata.isLocked());
System.out.println("Last Modified: " + metadata.getLastModifiedDate());
```

### Response Example (Get Workspace JSON)
```java
// Get workspace JSON (optionally with branch and version)
String json = workspaceComponent.getWorkspace(workspaceId, "", null);
String branchJson = workspaceComponent.getWorkspace(workspaceId, "feature-branch", null);
String versionedJson = workspaceComponent.getWorkspace(workspaceId, "", "20240115120000000");
```

### Request Example (Update Workspace)
```java
// Update workspace
workspaceComponent.putWorkspace(workspaceId, "", workspaceJsonString);
workspaceComponent.putWorkspace(workspaceId, "feature-branch", branchJsonString);
```

### Request Example (Lock/Unlock Workspace)
```java
// Lock/unlock workspace
boolean locked = workspaceComponent.lockWorkspace(workspaceId, "user@example.com", "my-client/1.0");
boolean unlocked = workspaceComponent.unlockWorkspace(workspaceId);
```

### Response Example (Get Workspace Versions)
```java
// Get workspace versions
List<WorkspaceVersion> versions = workspaceComponent.getWorkspaceVersions(workspaceId, "");
for (WorkspaceVersion version : versions) {
    System.out.println("Version: " + version.getVersionId() + " at " + version.getLastModifiedDate());
}
```

### Response Example (Get Workspace Branches)
```java
// Get workspace branches
List<WorkspaceBranch> branches = workspaceComponent.getWorkspaceBranches(workspaceId);
```

### Request Example (Workspace Visibility)
```java
// Workspace visibility
workspaceComponent.makeWorkspacePublic(workspaceId);
workspaceComponent.makeWorkspacePrivate(workspaceId);
workspaceComponent.shareWorkspace(workspaceId);   // Generate shareable link
workspaceComponent.unshareWorkspace(workspaceId);
```

### Request Example (Delete Workspace)
```java
// Delete workspace
boolean deleted = workspaceComponent.deleteWorkspace(workspaceId);
```
```

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

### Run Structurizr Docker with AWS S3 Storage

Source: https://context7.com/structurizr/onpremises/llms.txt

Run the Structurizr On-Premises Docker container configured to use AWS S3 for storage. Provide your AWS credentials and the path to the structurizr.properties file containing S3 configuration.

```bash
# Run with AWS S3 storage
docker run -d \
  -p 8080:8080 \
  -v /path/to/structurizr.properties:/usr/local/structurizr/structurizr.properties \
  -e AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
  -e AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  structurizr-onpremises
```

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

### Admin API - Workspace Management

Source: https://context7.com/structurizr/onpremises/llms.txt

API endpoints for administrators to manage workspaces, including listing, creating, and deleting them.

```APIDOC
## Admin API - Workspace Management

### List all workspaces

#### Method
GET

#### Endpoint
/api/workspace

#### Request Example
```bash
curl -X GET "https://structurizr.example.com/api/workspace" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

#### Response Example
```json
{
  "workspaces": [
    {
      "id": 1,
      "name": "Getting Started",
      "description": "Example workspace",
      "apiKey": "workspace-api-key",
      "apiSecret": "workspace-api-secret",
      "privateUrl": "https://structurizr.example.com/workspace/1",
      "publicUrl": "https://structurizr.example.com/share/1"
    }
  ]
}
```

### Create a new workspace

#### Method
POST

#### Endpoint
/api/workspace

#### Request Example
```bash
curl -X POST "https://structurizr.example.com/api/workspace" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

#### Response Example
```json
{
  "id": 2,
  "name": "Workspace 2",
  "apiKey": "generated-api-key",
  "apiSecret": "generated-api-secret",
  "privateUrl": "https://structurizr.example.com/workspace/2"
}
```

### Delete a workspace

#### Method
DELETE

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

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

#### Request Example
```bash
curl -X DELETE "https://structurizr.example.com/api/workspace/2" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

#### Response Example
```json
{
  "success": true,
  "message": "Workspace 2 deleted"
}
```
```

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

### Manage Workspace Visibility and Sharing

Source: https://context7.com/structurizr/onpremises/llms.txt

Functions to control workspace visibility (public/private) and generate shareable links.

```java
workspaceComponent.makeWorkspacePublic(workspaceId);
```

```java
workspaceComponent.makeWorkspacePrivate(workspaceId);
```

```java
workspaceComponent.shareWorkspace(workspaceId);
```

```java
workspaceComponent.unshareWorkspace(workspaceId);
```

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

### Configure Workspace Event Listener Plugin

Source: https://context7.com/structurizr/onpremises/llms.txt

Configure the custom WorkspaceEventListener plugin by specifying its fully qualified class name in the structurizr.properties file. Ensure the plugin JAR is placed in the data directory's plugins folder.

```properties
# structurizr.properties - Plugin configuration
# Package the plugin as a JAR in the data directory's plugins folder
structurizr.plugin.workspaceeventlistener=com.example.structurizr.plugins.AuditWorkspaceEventListener
```

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

### SearchComponent Interface

Source: https://context7.com/structurizr/onpremises/llms.txt

Provides full-text search across workspaces, indexing diagrams, documentation, and architecture decision records.

```APIDOC
## SearchComponent Interface

### Description
The SearchComponent provides full-text search across workspaces, indexing diagrams, documentation, and architecture decision records using Apache Lucene or Elasticsearch.

### Methods
- `isEnabled()`: Checks if the search functionality is enabled.
- `index(Workspace workspace)`: Indexes a given workspace (called automatically on PUT).
- `search(String query, String type, Set<Long> workspaceIds)`: Performs a full-text search across specified workspace IDs and content types.
- `delete(long workspaceId)`: Removes a workspace from the search index.

### Request Example (Search All Content Types)
```java
// Check if search is enabled
if (searchComponent.isEnabled()) {
    // Search across workspaces
    Set<Long> accessibleWorkspaceIds = Set.of(1L, 2L, 3L);

    // Search all content types
    List<SearchResult> results = searchComponent.search("authentication", null, accessibleWorkspaceIds);

    for (SearchResult result : results) {
        System.out.println("Workspace: " + result.getWorkspaceId());
        System.out.println("URL: " + result.getUrl());
        System.out.println("Name: " + result.getName());
        System.out.println("Description: " + result.getDescription());
        System.out.println("Type: " + result.getType());
    }
}
```

### Request Example (Search Specific Content Type)
```java
// Search specific content type: workspace, diagram, documentation, decision
List<SearchResult> diagramResults = searchComponent.search("login", "diagram", accessibleWorkspaceIds);
List<SearchResult> docResults = searchComponent.search("API design", "documentation", accessibleWorkspaceIds);
List<SearchResult> adrResults = searchComponent.search("microservices", "decision", accessibleWorkspaceIds);
```

### Request Example (Remove Workspace from Index)
```java
// Remove workspace from index
searchComponent.delete(workspaceId);
```
```

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

### Unlock a Structurizr Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Use this command to unlock a workspace. Ensure HMAC content and authorization headers are correctly constructed.

```bash
HMAC_CONTENT="DELETE
/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}
${CONTENT_MD5}

${NONCE}
"

HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X DELETE "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}"
```

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

### Workspace API - Put Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Updates a workspace with new JSON content. The request body must be valid Structurizr workspace JSON and the Content-MD5 header must match.

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

### Description
Updates an existing workspace with the provided JSON content. The `Content-MD5` header must accurately reflect the MD5 hash of the request body.

### Method
PUT

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

### Headers
- **Authorization** (string) - Required - HMAC-SHA256 signature in the format "{apiKey}:{base64EncodedHmac}".
- **Nonce** (string) - Required - A unique, monotonically increasing number (e.g., Unix timestamp).
- **Content-MD5** (string) - Required - Base64 encoded MD5 hash of the request body.
- **Content-Type** (string) - Required - Specifies the content type of the request body, typically "application/json; charset=UTF-8".

### Request Body
- **workspace** (object) - Required - The complete workspace JSON object to update.
  - **id** (integer) - Required - The ID of the workspace.
  - **name** (string) - Required - The name of the workspace.
  - **description** (string) - Optional - A description for the workspace.
  - **model** (object) - Required - The architecture model.
  - **views** (object) - Required - The architecture views.

### Request Example
```bash
WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)

WORKSPACE_JSON='{
  "id": 1,
  "name": "Getting Started",
  "description": "A simple example workspace",
  "model": {
    "people": [
      {"id": "1", "name": "User", "description": "A user of the system"}
    ],
    "softwareSystems": [
      {"id": "2", "name": "Software System", "description": "My software system"}
    ]
  },
  "views": {
    "systemContextViews": [
      {"softwareSystemId": "2", "key": "SystemContext", "elements": [{"id": "1"}, {"id": "2"}]}
    ]
  }
}'

CONTENT_MD5=$(echo -n "$WORKSPACE_JSON" | md5sum | awk '{print $1}')
CONTENT_MD5_HEADER=$(echo -n "$CONTENT_MD5" | base64)

HMAC_CONTENT="PUT\n/api/workspace/${WORKSPACE_ID}\n${CONTENT_MD5}\napplication/json; charset=UTF-8\n${NONCE}"

HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X PUT "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: ${CONTENT_MD5_HEADER}" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d "$WORKSPACE_JSON"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message confirming the status (e.g., "OK").

#### Response Example
```json
{
  "success": true,
  "message": "OK"
}
```
```

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

### Update Structurizr Workspace JSON

Source: https://context7.com/structurizr/onpremises/llms.txt

Updates a workspace with new JSON content using HMAC-SHA256 authentication. The Content-MD5 header must match the MD5 hash of the request body, and the Content-Type should be 'application/json; charset=UTF-8'.

```bash
# Update workspace
WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)

# Workspace JSON content
WORKSPACE_JSON='{
  "id": 1,
  "name": "Getting Started",
  "description": "A simple example workspace",
  "model": {
    "people": [
      {"id": "1", "name": "User", "description": "A user of the system"}
    ],
    "softwareSystems": [
      {"id": "2", "name": "Software System", "description": "My software system"}
    ]
  },
  "views": {
    "systemContextViews": [
      {"softwareSystemId": "2", "key": "SystemContext", "elements": [{"id": "1"}, {"id": "2"}]}
    ]
  }
}'

# Calculate MD5 hash of content
CONTENT_MD5=$(echo -n "$WORKSPACE_JSON" | md5sum | awk '{print $1}')
CONTENT_MD5_HEADER=$(echo -n "$CONTENT_MD5" | base64)

# Generate HMAC
HMAC_CONTENT="PUT
/api/workspace/${WORKSPACE_ID}
${CONTENT_MD5}
application/json; charset=UTF-8
${NONCE}
"

HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X PUT "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}" \
  -H "Content-MD5: ${CONTENT_MD5_HEADER}" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d "$WORKSPACE_JSON"

# Response: {"success":true,"message":"OK"}
```

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

### HMAC Authentication Client Implementation in Java

Source: https://context7.com/structurizr/onpremises/llms.txt

Java client implementation for API authentication using HMAC-SHA256. This snippet demonstrates how to generate the necessary authentication headers for API requests, including calculating the HMAC signature over the request details and encoding it.

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;
import java.util.Base64;

public class StructurizrApiClient {

    private final String apiKey;
    private final String apiSecret;
    private final String baseUrl;

    public StructurizrApiClient(String baseUrl, String apiKey, String apiSecret) {
        this.baseUrl = baseUrl;
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
    }

    public String getWorkspace(long workspaceId) throws Exception {
        String path = "/api/workspace/" + workspaceId;
        String nonce = String.valueOf(System.currentTimeMillis());
        String contentMd5 = md5("");  // Empty content for GET

        String hmacContent = String.join("\n",
            "GET",
            path,
            contentMd5,
            "",  // No content type for GET
            nonce,
            ""
        );

        String hmac = generateHmac(hmacContent, apiSecret);
        String authHeader = apiKey + ":" + Base64.getEncoder().encodeToString(hmac.getBytes());

        // Make HTTP request with headers:
        // Authorization: {authHeader}
        // Nonce: {nonce}
        // Content-MD5: {base64(contentMd5)}
        return executeGet(baseUrl + path, authHeader, nonce, contentMd5);
    }

    public void putWorkspace(long workspaceId, String json) throws Exception {
        String path = "/api/workspace/" + workspaceId;
        String nonce = String.valueOf(System.currentTimeMillis());
        String contentMd5 = md5(json);
        String contentType = "application/json; charset=UTF-8";

        String hmacContent = String.join("\n",
            "PUT",
            path,
            contentMd5,
            contentType,
            nonce,
            ""
        );

        String hmac = generateHmac(hmacContent, apiSecret);
        String authHeader = apiKey + ":" + Base64.getEncoder().encodeToString(hmac.getBytes());

        // Make HTTP request with headers:
        // Authorization: {authHeader}
        // Nonce: {nonce}
        // Content-MD5: {base64(contentMd5)}
        // Content-Type: {contentType}
        executePut(baseUrl + path, authHeader, nonce, contentMd5, contentType, json);
    }

    private String generateHmac(String content, String secret) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
        byte[] rawHmac = mac.doFinal(content.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : rawHmac) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }

    private String md5(String content) throws Exception {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(content.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}
```

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

### Delete a Structurizr Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

This command deletes a specified workspace using its ID via the Admin API. An admin API key is necessary.

```bash
curl -X DELETE "https://structurizr.example.com/api/workspace/2" \
  -H "X-Authorization: ${ADMIN_API_KEY}"
```

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

### Workspace API - Lock and Unlock

Source: https://context7.com/structurizr/onpremises/llms.txt

Locks a workspace to prevent concurrent modifications. Locks automatically expire after 2 minutes. User and agent parameters are required.

```APIDOC
## PUT /api/workspace/{workspaceId}/lock

### Description
Acquires a lock on a workspace to prevent concurrent edits. The lock automatically expires after 2 minutes. The `user` and `agent` parameters identify the entity holding the lock.

### Method
PUT

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

### Query Parameters
- **user** (string) - Required - The identifier of the user or system attempting to lock the workspace (e.g., "developer@example.com").
- **agent** (string) - Required - The identifier of the agent or client performing the action (e.g., "structurizr-java/1.2.3").

### Headers
- **Authorization** (string) - Required - HMAC-SHA256 signature in the format "{apiKey}:{base64EncodedHmac}".
- **Nonce** (string) - Required - A unique, monotonically increasing number (e.g., Unix timestamp).

### Request Example
```bash
WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)
USER="developer@example.com"
AGENT="structurizr-java/1.2.3"

CONTENT_MD5="d41d8cd98f00b204e9800998ecf8427e"

HMAC_CONTENT="PUT\n/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}\n${CONTENT_MD5}\n\n${NONCE}"

HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X PUT "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the lock was acquired successfully.
- **message** (string) - A confirmation message (e.g., "OK").

#### Response Example
```json
{
  "success": true,
  "message": "OK"
}
```

### Unlock Workspace
To unlock a workspace, a `DELETE` request to the `/api/workspace/{workspaceId}/lock` endpoint is used, typically with the same `user` and `agent` parameters to identify the lock holder.

```bash
# Example for unlocking (assuming DELETE method is supported for unlock)
curl -X DELETE "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}"
```
```

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

### Workspace Lock API

Source: https://context7.com/structurizr/onpremises/llms.txt

API endpoint for managing workspace locks. This includes unlocking a workspace.

```APIDOC
## DELETE /api/workspace/{workspaceId}/lock

### Description
Unlocks a workspace, allowing other users or applications to modify it.

### Method
DELETE

### Endpoint
/api/workspace/${WORKSPACE_ID}/lock

### Parameters
#### Query Parameters
- **user** (string) - Required - The user attempting to unlock the workspace.
- **agent** (string) - Required - The agent or application used by the user.

### Request Example
```bash
curl -X DELETE "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message confirming the unlock status.

#### Response Example
```json
{
  "success": true,
  "message": "OK"
}
```

#### Error Response (409 Conflict)
- **success** (boolean) - Always false.
- **message** (string) - Describes the conflict, e.g., if the workspace is already locked by another user.

#### Error Response Example
```json
{
  "success": false,
  "message": "The workspace is already locked by user1@example.com using structurizr-web/123."
}
```
```

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

### Lock Structurizr Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Locks a workspace to prevent concurrent modifications using HMAC-SHA256 authentication. Locks expire after 2 minutes. The user and agent parameters are required to identify the lock holder.

```bash
# Lock a workspace
WORKSPACE_ID=1
API_KEY="your-api-key"
API_SECRET="your-api-secret"
NONCE=$(date +%s)
USER="developer@example.com"
AGENT="structurizr-java/1.2.3"

CONTENT_MD5="d41d8cd98f00b204e9800998ecf8427e"

HMAC_CONTENT="PUT
/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}
${CONTENT_MD5}

${NONCE}
"

HMAC=$(echo -n "$HMAC_CONTENT" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
AUTH_HEADER="${API_KEY}:$(echo -n "$HMAC" | base64)"

curl -X PUT "https://structurizr.example.com/api/workspace/${WORKSPACE_ID}/lock?user=${USER}&agent=${AGENT}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -H "Nonce: ${NONCE}"

# Response if successful: {"success":true,"message":"OK"}
```

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

### Delete Workspace

Source: https://context7.com/structurizr/onpremises/llms.txt

Removes a workspace and all its associated data. This operation is irreversible.

```java
boolean deleted = workspaceComponent.deleteWorkspace(workspaceId);
```
Tokens:
Raw