Getting Started
To start with the tutorial there are two options:
- Open blank playground in a new tab
- Install vscode extension
and follow the steps:
-
Prepare specification
We start with defining kinds of the elements in our architecture.
We need only two -actor
andsystem
:tutorial.c4 specification {element actorelement system} -
Create model
Start with top-level and define the model:
tutorial.c4 specification {element actorelement system}model {customer = actor 'Customer'saas = system 'Our SaaS'}These are the first elements of our architecture model.
Let’s add details. -
Add hierarchy
Assume our system has two main components -
ui
andbackend
.
We add a new kind to the specification and update the model.tutorial.c4 specification {element actorelement systemelement component}model {customer = actor 'Customer'saas = system 'Our SaaS' {component uicomponent backend}} -
Add relationships
Any links between elements (i.e. interactions, calls, delegations, dependencies, flows). You are free to define them as you like.
In the model:
tutorial.c4 specification {element actorelement systemelement component}model {customer = actor 'Customer'saas = system 'Our SaaS' {component uicomponent backend// UI fetches data from the Backendui -> backend}// Customer uses the UIcustomer -> ui 'opens in browser'} -
Create first diagram
Diagrams are rendered from views, and views are projections of the model defined by predicates (what to include/exclude).
Start with bird’s eye view (“Landscape”):
tutorial.c4 specification {element actorelement systemelement component}model {customer = actor 'Customer'saas = system 'Our SaaS' {component uicomponent backend// UI fetches data from the Backendui -> backend// Customer uses the UIcustomer -> ui 'opens in browser'}}views {view index {include *}}We got this:
-
Add more views
tutorial.c4 specification {element actorelement systemelement component}model {customer = actor 'Customer'saas = system 'Our SaaS' {component uicomponent backend// UI requests data from the Backendui -> backend// Customer uses the UIcustomer -> ui 'opens in browser'}}views {view index {include *}view of saas {include *}}Imagine, we zoom in to
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 relationshipui -> backend
tutorial.c4 specification {element actorelement systemelement 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 logicand exposes as REST API'}// UI fetches data from the Backendui -> backend 'fetches via HTTPS'}// Customer uses the UIcustomer -> ui 'opens in browser'}views {view index {title 'Landscape view'include *}view of saas {include *style customer {color muted}}}The
saas
view after changes: -
Add changes
Let’s change the description of the
customer
and the label ofcustomer -> ui
tutorial.c4 specification {element actorelement systemelement component}model {customer = actor 'Customer' {description 'The regular customer of the system'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 logicand exposes as REST API'}// UI requests data from the Backendui -> backend 'fetches via HTTPS'}// Customer uses the UIcustomer -> ui 'opens in browser'customer -> ui 'enjoys our product'}views {view index {title 'Landscape view'include *}view of saas {include *style customer {color muted}}}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
Open playground Play with this tutorial in playground - change shape of the