Primeiros passos

Para iniciar o tutorial, você tem duas opções:

• Abra o Playground vazio em uma nova aba
• Instale a extensão para VS Code (ou pelo Open VSX) e crie um novo arquivo com a extensão .c4

Depois, siga estas etapas:

1. Preparar a especificação

   Vamos começar definindo os tipos de elementos que existirão em nossa arquitetura. Precisamos apenas de dois: actor e system:

   tutorial.c4

   specification {
     element actor
     element system
   }

2. Criar o modelo

   Comece pelos elementos de nível superior e defina o modelo:

   tutorial.c4

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

   Estes são os primeiros elementos do nosso modelo de arquitetura. Agora vamos adicionar mais detalhes.

3. Adicionar uma hierarquia

   Considere que nosso sistema possui dois componentes principais: ui e backend. Vamos adicionar um novo tipo à especificação e atualizar o modelo.

   tutorial.c4

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

4. Adicionar relacionamentos

   Qualquer ligação entre elementos — por exemplo, interações, chamadas, delegações, dependências ou fluxos — pode ser representada como um relacionamento. Você pode defini-los da forma que fizer mais sentido para o seu modelo.

   No modelo:

   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. Criar o primeiro diagrama

   Os diagramas são renderizados a partir de visões (views). As visões são projeções do modelo definidas por predicados, que determinam o que deve ser incluído ou excluído.

   Comece com uma visão panorâmica (“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 *
     }
   }

   O resultado é este:

   

   Por que há um relacionamento?

   O predicado include * inclui apenas os elementos de “nível superior” e infere os relacionamentos entre eles a partir dos elementos aninhados:

   customer possui um relacionamento conhecido com o elemento aninhado saas.ui

   Isso implica que:

   customer possui algum relacionamento com saas.

6. Adicionar mais visões

   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 que aproximamos o foco no elemento saas para visualizar seus elementos aninhados e os relacionamentos entre eles:

   

7. Enriquecer o modelo

   Vamos adicionar descrições, definir a forma (shape) do ui e incluir um rótulo no relacionamento 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
       }
     }
   
   }

   A visão saas após as alterações:

   

8. Fazer alterações no modelo

   Vamos alterar a descrição de customer e o rótulo do relacionamento 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
       }
     }
   
   }

   Visão index:

   

   Visão saas:

   

   Percebeu?

   Alteramos elementos no modelo e todas as visões foram atualizadas de acordo com essas mudanças.

9. Experimente você mesmo

   Explore este tutorial no Playground e tente fazer o seguinte:

   • altere a forma (shape) do elemento customer
   • adicione um banco de dados (usando a forma storage) e tabelas como customers e orders — quais relacionamentos deveriam ser adicionados?
   • adicione um sistema externo, como o Stripe, e mostre como o backend poderia interagir com ele
   Abrir o PlaygroundExperimente este tutorial diretamente no Playground