Relationships

Relationships describe the connections, data flows and interactions of the elements,
and created with the -> operator:

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

  customer -> cloud
}

Relationship kinds

Relationships can be “kinded”:

specification {
  element system
  // Define a relationship kind in specification
  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 allows us to express and add more semantics to the interactions between the elements, for instance, from a technology perspective (REST, GRPC, GraphQL, Sync/Async, etc.) or from a business perspective (delegation, inform, accountability, etc.).
It’s up to you to define the relationship kinds that make sense for your context.

Tip

The relationship kinds allow to customize the styling of the relationships, see styling

Examples

Relationships may be nested

model {
  actor customer
  service cloud {
    component backend
    component frontend

    frontend -> backend
    customer -> frontend
  }
}

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

model {
  actor customer
  service cloud {
    component backend
    component frontend

    frontend -> backend 'requests data'
  }

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

Relationships may be tagged

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

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

Relationships may have multiple links:

model {
  customer -> frontend 'opens in browser' {
    // External link
    link https://any-external-link.com

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

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

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

specification {
  relationship graphql
}
model {
  customer = actor {
    -> frontend 'opens in browser' // same as customer -> frontend
  }
  service cloud {
    component backend
    component frontend {
      -[graphql]-> backend 'requests data'  // same as frontend -[graphql]-> backend
    }
  }

  // or use 'it' or 'this'
  customer = actor {
    it -> frontend 'opens in browser'
    this -> frontend 'opens in browser'
  }

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