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 and underscore, but can’t start with a digit or contain .

name
api	✅
Api2	✅
_api	✅
__Api1	✅
1api	⛔️
a.pi	⛔️

Element Properties

Elements may have properties: title, description and technology.
For example:

specification {
  element softwareSystem
}
model {
  // Structurizr DSL style:
  // <name> = softwareSystem [title] [description] [technology]
  cloud = softwareSystem 'Cloud' 'Provides services to customers' 'SaaS'
}

LikeC4 supports Structurizr DSL syntax (“partially”) allowing to copy-paste from it.
Check the Big Bank example.

All properties are optional, and element’s name will be used as a title by default:

model {
  // element of kind 'actor'  with name='customer' and title='customer'
  actor customer
  // element of kind 'service' with name='cloud' and title='Cloud Systems'
  service cloud 'Cloud Systems'

  // or with '='
  cloud = service 'Cloud Systems'
}

Note

You can use single or double quotes:

specification {
  service cloud 'Cloud Systems'
  // Or
  service cloud "Cloud Systems"
}

If you need quotes inside, you can escape with backslash:

specification {
  service cloud 'Cloud\'s Systems'
  service cloud "Cloud\"s Systems"
}

These properties may be defined as nested:

model {
  // Only description inside
  customer = actor 'Customer' {
    description: 'Uses the Mobile Application' // ':' is optional, but if you prefer
  }
  // All properties inside
  mobile = application {
    title 'Mobile Application'
    description 'Provides services to customers'
    technology 'React Native'
  }
  // Multiline
  web = application {
    title 'Web Application'
    description '
      Provides services to customers through
      the web interface.
    '
  }
}

Tip

You may define technology in specification, if it is common for all of the kind:

specification {
  element mobileApp {
    technology 'React Native'
  }
}

Markdown

You can use markdown in description 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    | ✅  |
    """
  }
}

Element Tags

Tags are defined in nested block and 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 to element kind in specification, if it is common for all of the kind:

specification {
  element lambda {
    #serverless
  }
}

Element Links

Element may have multiple links:

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

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

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

Element 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: {}
      '
    }
  }
}

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

Structure

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

Caution

Element name must be unique within the container.
We learn this in detail with references

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

It is not possible to have elements with the same name on the same hierarchy level.

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'
}