Docs
Tutorial

Quick Tutorial

To start with tutorial

and follow the steps:

Tailor specification

We start with defining the element kinds we use in our model.
For now, we need only two - actor and system

getting-started.c4
specification {
  element actor
  element system
}

Define the first elements

Start with top-level architecture elements

getting-started.c4
specification {
  element actor
  element system
}
 
model {
  customer = actor 'Customer'
  saas = system 'Our SaaS'
}

Add nested elements

Assume our system has two main components - ui and backend.
We add a new kind to the specification and update the model.

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer'
  saas = system 'Our SaaS' {
    component ui
    component backend
  }
}

Add relationships

Relationships describe the connections and interactions of the elements.

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer'
  saas = system 'Our SaaS' {
    component ui
    component backend
 
    // UI fetches data from the Backend
    ui -> backend
  }
 
  // Customer uses the UI
  customer -> ui 'opens in browser'
}

Landscape view

View is a projection, a slice of the model defined by predicates (what to include/exclude).
Let's add the Landscape view, i.e. bird's eye view of the architecture.

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer'
  saas = system 'Our SaaS' {
    component ui
    component backend
 
    // UI fetches data from the Backend
    ui -> backend
 
    // Customer uses the UI
    customer -> ui 'opens in browser'
  }
}
 
views {
 
  view index {
    include *
  }
 
}

We got this:

landscape view

Why there is a relationship?

The relationships are implied from the nested elements.

  • customer has a known relationship with the nested saas.ui element

that implies

  • customer has some relationship with saas.

Add more views

A View may have a root element view of ... as the initial scope.
Then predicate include * is applied to the root element and includes nested elements.
This is covered in more detail in LikeC4 Language - Views.

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer'
  saas = system 'Our SaaS' {
    component ui
    component backend
 
    // UI requests data from the Backend
    ui -> backend
 
    // Customer uses the UI
    customer -> ui 'opens in browser'
  }
}
 
views {
 
  view index {
    title 'Landscape view'
 
    include *
  }
 
  view of saas {
    include *
  }
 
}

Imagine, we zoom in on the saas element, and see nested elements and their relationships:

saas view

Enrich model

Let's add descriptions, define the shape of the ui and add a label to the relationship ui -> backend

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer' {
    description 'The regular customer of the system'
  }
 
  saas = system 'Our SaaS' {
    component ui 'Frontend' {
      description 'Nextjs application, hosted on Vercel'
      style {
        shape browser
      }
    }
    component backend 'Backend Services' {
      description '
        Implements business logic
        and exposes as REST API
      '
    }
 
    // UI fetches data from the Backend
    ui -> backend 'fetches via HTTPS'
  }
 
  // Customer uses the UI
  customer -> ui 'opens in browser'
}
 
views {
 
  view index {
    title 'Landscape view'
 
    include *
  }
 
  view of saas {
    include *
 
    style customer {
      color muted
    }
  }
 
}

The saas view after changes:

saas view after changes

Change model

Let's change the description of the customer and the label of customer -> ui

getting-started.c4
specification {
  element actor
  element system
  element component
}
 
model {
  customer = actor 'Customer' {
    description 'Our dear customer'
  }
 
  saas = system 'Our SaaS' {
    component ui 'Frontend' {
      description 'Nextjs application, hosted on Vercel'
      style {
        shape browser
      }
    }
    component backend 'Backend Services' {
      description '
        Implements business logic
        and exposes as REST API
      '
    }
 
    // UI requests data from the Backend
    ui -> backend 'fetches via HTTPS'
  }
 
  // Customer uses the UI
  customer -> ui 'enjoys our product'
}
 
views {
 
  view index {
    title 'Landscape view'
 
    include *
  }
 
  view of saas {
    include *
 
    style customer {
      color muted
    }
  }
 
}

When we make changes, all views are updated automatically.

View index:

landscape view after changes

View saas:

saas view after changes

Try it yourself

Play with this tutorial in playground and try to add the following:

  • change shape of the customer element
  • add a database (with storage shape) and tables like customers and orders (what relationships should be added?)
  • add an external system, like Stripe, and show how the backend might interact with it
Getting StartedLikeC4 Language