Relationships

Relationships describe the connections, data flows and interactions within your model.

Relationship definition

Relationships are defined with the -> operator:

model {
  customer = actor 'Customer'
  cloud = service 'Cloud'

  customer -> cloud
}

Relationships may be nested

model {
  service cloud {
    component backend
    component frontend

    frontend -> backend
    customer -> frontend
  }
}

In nested relationships you can use it or this to refer parent:

model {
  customer = actor {
    // as a source
    it -> frontend
    // as a target
    frontend -> this
  }
}

Nested relationships may be “sourceless”, then the source is the parent element

model {
  actor customer {
    // same as customer -> frontend
    -> frontend
  }
  service cloud {
    component backend
    component frontend {
      // same as frontend -> backend
      -> backend
    }
  }
}

Caution

“sourceless” relationships must be nested:

model {
  -> backend // ⛔️ Error: model can't be a source
}

Relationship kinds

Relationships can be “kinded”:

specification {
  element system
  // Define relationship kind
  relationship async
  relationship uses
}

model {
  system1 = system 'System 1'
  system2 = system 'System 2'

  system1 -[async]-> system2

  // Or prefix with '.' to use the kind
  system1 .uses system2
}

This makes it possible to add richer semantics to the interactions between elements, for example, from a technology perspective (REST, gRPC, GraphQL, Sync/Async, etc.) or from a business perspective (delegation, informing, accountability, etc.).

You can define whichever relationship types best fit your context.

Tip

With kinds you can customize the styling of the relationships, see styling

Relationship Properties

Title

Relationships may have a title (and better to have one):

model {
  customer -> frontend 'opens in browser'
  // or nested
  customer -> frontend {
    title 'opens in browser'
  }
}

Description

model {
  customer -> frontend 'opens in browser' {
    description 'Customer opens...'
  }

  // Or in a shorter way
  customer -> frontend 'opens in browser' 'Customer opens...'
}

Same as for elements, you can use markdown in description with triple quotes:

model {
  customer -> frontend 'opens in browser' {
    description '''
      **Customer** opens the frontend in the browser
      to interact with the system


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

Technology

model {
  customer -> frontend 'opens in browser' {
    technology 'HTTPS'
  }

  // Or in a shorter way
  // order is [title] [description] [technology]
  customer -> frontend 'opens in browser'  'Customer opens...' 'HTTPS'
}

Tags

Relationships may have tags:

model {
  // inlined
  frontend -> backend 'requests data' #graphql #team1

  // or nested
  customer -> frontend 'opens in browser' {
    #graphql #team1
  }
}

Links

Relationships may have multiple links:

model {
  customer -> frontend 'opens in browser' {
    // 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
  }
}

Navigate To

Relationship may have a navigateTo property, which is a link to dynamic view.
This allows to “zoom-in” and see more details about this relationship.

model {
  webApp -> backend.api {
    title 'requests data for the dashboard'
    navigateTo dashboard-request-flow
  }

}

Relationships Metadata

Same as elements metadata:

model {
  customer -> frontend 'opens in browser' {
    metadata {
      prop1 'value1'
      prop2 '{
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "integer"
          }
        }
      }'
    }
  }
}