Getting Started

To start the tutorial, you have two options:

• Open blank playground in a new tab
• Install vscode extension (or open-vsx) and create a new file with .c4 extension

and follow the steps:

1. Prepare the specification

   We’ll start by defining the kinds of elements in our architecture. We only need two - actor and system:

   tutorial.c4

   specification {
     element actor
     element system
   }

2. Create the model

   Start with the top-level elements and define the model:

   tutorial.c4

    specification {
      element actor
      element system
    }
   
    model {
      customer = actor 'Customer'
      saas = system 'Our SaaS'
    }

   These are the first elements of our architecture model.
   Let’s add details.

3. Add a hierarchy

   Assume our system has two main components: ui and backend. Let’s add a new kind to the specification and update the model.

   tutorial.c4

   specification {
     element actor
     element system
     element component
   }
   
   model {
     customer = actor 'Customer'
     saas = system 'Our SaaS' {
       component ui
       component backend
     }
   }

4. 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 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'
   }

5. Create first diagram

   Diagrams are rendered from views. Views are projections of the model defined by predicates (what to include or exclude).

   Start with a bird’s eye view (“Landscape”):

   tutorial.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:

   

   Wondering why there is a relationship?

   The predicate include * includes only “top-level” elements and infers relationships between them from nested elements:

   customer has a known relationship with nested saas.ui element

   that implies:

   customer has some relationship with saas.

6. Add more views

   tutorial.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 {
       include *
     }
   
     view of saas {
       include *
     }
   }

   Imagine we zoom in to the saas element and see its nested elements and their relationships:

   

7. Enrich the model

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

   tutorial.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 {
           icon tech:nextjs
           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:

   

8. Add changes

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

   tutorial.c4

   specification {
     element actor
     element system
     element 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 {
           icon tech:nextjs
           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 'opens in browser'
     customer -> saas 'enjoys our product'
   }
   
   views {
   
     view index {
       title 'Landscape view'
   
       include *
     }
   
     view of saas {
       include *
   
       style customer {
         color muted
       }
     }
   
   }

   View index:

   

   View saas:

   

   Did you see?

   We changed elements in the model, and all views are updated accordingly.

9. Try it yourself

   Play with this tutorial in the playground and try adding 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
   Open playground Play with this tutorial in playground