Model

The model describes architecture as a set of hierarchical elements and any relationships among them.

Element

Element is a basic building block. It represents a logical part of the architecture.
Any element must have a kind and a name (identifier):

specification {
  element actor
  element service
}

model {
  // element of kind 'actor' with the name 'customer'
  actor customer
  // element of kind 'service' named as 'cloud'
  service cloud

  // also possible with '=' and the name goes first
  cloud = service
}

Element name is required for references.
It can contain letters, digits, hyphens and underscore, but can’t start with a digit or contain .

name	valid
api	✅
Api2	✅
_api	✅
__Api-1	✅
1api	⛔️
a.pi	⛔️

Element Properties

Title

specification {
  element softwareSystem
}
model {
  // Title can be inlined
  saas = softwareSystem 'SaaS'

  // or nested
  saas = softwareSystem {
    title 'SaaS'

    // You can use `:` (optional)
    title: 'SaaS'
  }

  // If title is not specified, name will be used by default
  saas = softwareSystem
}

Note

You can use single or double quotes:

model {
  service cloud 'Cloud Service'
  // Or
  service cloud "Cloud Service"
}

If you need quotes inside, escape with backslash:

model {
  service cloud 'Cloud\'s Service'
  service cloud "Cloud\"s Service"
}

Description

model {
  // Can be inlined
  saas = softwareSystem 'SaaS' 'Provides services to customers'

  // or nested
  saas = softwareSystem {
    title 'SaaS'
    description 'Provides services to customers'
  }
}

Element may have a short summary (optional, falls back to description):

model {
  saas = softwareSystem {
    title 'SaaS'
    summary 'Provides services to customers'
    description '
      Detailed description
      ...
    '
  }
}

If summary is provided, it will be shown on the diagram, and description in the details dialog.
If you don’t provide description, summary will be used.

For inlined definition:

model {
  // [title] [summary]
  saas = softwareSystem 'SaaS' 'Provides services to customers' {
    description '
      Detailed description
      ...
    '
  }
}

Technology

model {
  api = service {
    technology 'REST'
  }

  // Structurizr DSL style:
  // <name> = softwareSystem [title] [summary] [technology]
  saas = softwareSystem 'SaaS' 'Provides services to customers' 'SaaS'
}

Tip

You can define element properties in specification, if it is common for all of the kind:

specification {
  element mobileApp {
    title 'Mobile App'
    description 'Universal mobile application'
    technology 'React Native'
  }
}

This allows to define properties once and reuse them across the model.
Properties from the element definition override the ones from the specification.

Tags

Element tags are defined in a nested block and must come first, before any properties:

model {
  appV1 = application 'App v1' {
    #deprecated
    description 'Old version of the application'
  }

  // multiple tags
  appV2 = application {
    #next, #serverless
    #team2
    title 'App v2'
  }

  appV3 = application {
    title 'App v3'
    #team3 // ⛔️ Error: tags must be defined first
  }
}

Tip

You can add tags in the specification, if it is common for all of the kind:

specification {
  element lambda {
    #serverless
  }
}

Links

Element may have multiple links:

model {
  bastion = application 'Bastion' {
    // External link
    link https://any-external-link.com

    // With label
    link https://github.com/likec4/likec4 'Repository'

    // or any URI
    link ssh://bastion.internal 'SSH'

    // or relative link to navigate to sources
    link ../src/index.ts#L1-L10
  }
}

Metadata

Element metadata is a set of key-value pairs, defined in a nested block:

model {
  app = application 'App' {
    metadata {
      prop1 'value1'
      prop2 '
        apiVersion: apps/v1
        kind: StatefulSet
        metadata:
          name: app-statefulset
        spec: {}
      '
      prop3 '{
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "integer"
          }
        }
      }'
    }
  }
}

Only string values are allowed, but you can use JSON or YAML format for complex data.

Using Markdown

You can use markdown in description (and summary) with triple quotes:

model {
  mobile = application {
    title 'Mobile Application'
    description '''
      ### Multi-platform application

      [React Native](https://reactnative.dev)
    '''
  }

  web = application {
    description """
      ### Web Application

      > Provides services to customers through
      > the web interface.

      | checks     |     |
      | :--------- | :-- |
      | check 1    | ✅  |
      | check 2    | ⛔️  |
      | check 3    | ✅  |
    """
  }
}

Structuring Model

Any element is a container and can contain other elements.
This way you define the structure and internals of the element.

model {
  // service1 has backend and frontend
  service service1 {
    component backend {
      // backend has api
      component api
    }
    component frontend
  }

  // or use '='
  service2 = service {
    backend = component {
      api = component
    }
    frontend = component
  }
}

Nested elements are “namespaced”, the parent name is used as a prefix.
So, the model above has the elements with these fully qualified names:

• service1
• service1.backend
• service1.backend.api
• service1.frontend

and:

• service2
• service2.backend
• service2.backend.api
• service2.frontend

Caution

It is not possible to have elements with the same name on the same hierarchy level.
It is explained in detail in references.

model {

  service service1 'Service 1' {
    component backend

    component backend // ⛔️ Error: 'service1.backend' already defined
  }

  service service2 'Service 2' {
    component backend // ✅ This is OK - 'service2.backend'

    component legacy {
      component backend // ✅ This is OK - 'service2.legacy.backend'
    }
  }

  component backend // ✅ This is OK - 'backend'
}