Getting Started

To start with the tutorial there are 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 specification

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

   tutorial.c4

   specification {
     element actor
     element system
   }

2. Create model

   Start with top-level 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 hierarchy

   Assume our system has two main components - ui and backend.
   We 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, 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 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:

   

   Wonder why there is a relationship?

   The predicate include * includes only “top-level” elements and implies 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 saas element, and see nested elements and their relationships:

   

7. Enrich 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 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
   Open playground Play with this tutorial in playground