Quick Tutorial
To start with tutorial
- Web: open blank playground in a new tab
- Local: install vscode extension (opens in a new tab)
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
specification {
element actor
element system
}
Define the first elements
Start with top-level architecture elements
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.
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.
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.
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:
Why there is a relationship?
The relationships are implied from the nested elements.
customer
has a known relationship with the nestedsaas.ui
element
that implies
customer
has some relationship withsaas
.
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.
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:
Enrich model
Let's add descriptions, define the shape of the ui
and add a label to the relationship ui -> backend
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:
Change model
Let's change the description of the customer
and the label of customer -> ui
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
:
View saas
:
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 likecustomers
andorders
(what relationships should be added?) - add an external system, like Stripe, and show how the backend might interact with it