Na concepção de novos projetos, especialmente em papéis como desenvolvedor sênior, liderança técnica ou especialista, é comum que profissionais participem desde as definições de negócio até a criação de soluções técnicas. Para facilitar a comunicação entre as áreas de tecnologia e negócio, o C4 Model surge como uma abordagem eficaz para representar visualmente a arquitetura do sistema.
Utilizando ferramentas como a StackSpot AI, que simplifica e acelera o desenvolvimento de software, é possível integrar inteligência artificial generativa ao processo, otimizando a criação de diagramas de arquiteturas e garantindo que as expectativas de todas as partes envolvidas sejam atendidas de forma clara e precisa.
Neste artigo, vamos ver como montar um C4 Model de forma eficiente e prática usando o poder da AI contextualizada, da StackSpot AI.
O que é a StackSpot AI?
A StackSpot AI é uma assistente de Inteligência Artificial contextualizada que integra modelos AI generativa em todo o ciclo de desenvolvimento de software, oferecendo respostas assertivas para o seu projeto e comandos rápidos para automatizar tarefas repetitivas.
Agora, vamos conferir alguns conceitos de funcionalidades da StackSpot AI:
Knowledge Sources da StackSpot AI
Uma das principais funcionalidades da StackSpot AI são os Knowledge Sources (KS), que desempenham um papel fundamental na geração de respostas contextualizadas e assertivas.
Com os Knowledge Sources, podemos adicionar ainda contexto aos nossos prompts, melhorando significativamente os resultados.
Saiba mais sobre Knowledge Sources na documentação da StackSpot AI.
Quick Commands da StackSpot AI
Uma das funcionalidades mais relevantes da StackSpot AI são os de Quick Commands, instruções predefinidas que podem ser enviadas para a Large Language Model (LLM) para executar ações específicas, fornecendo maneiras rápidas e eficientes de contextualizar a LLM.
Em outras palavras, é uma maneira de automatizar um workflow de prompt de comandos.
Saiba mais sobre Quick Commands na documentação da StackSpot AI.
O que é C4 Model e quais seus benefícios?
Quem trabalha com Engenharia de Software sabe da dificuldade de manter diferentes níveis de documentação, como guias de instalação e utilização do projeto, arquitetura do software, histórico de releases, entre outros.
Focando no cenário específico da arquitetura de software, o C4 Model surgiu para aumentar a eficácia na criação de documentações.
Agora, imagine utilizar uma linguagem de programação como o PlantUML para criar diagramas em diferentes níveis e, de quebra, manter a documentação versionada dentro do projeto ou em um repositório específico.
Os ganhos de produtividade são significativos. O que antes poderia levar uma sprint (considerando que uma sprint dura, em média, duas semanas) para ser documentado, agora pode ser feito em 2 ou 3 dias. Além disso, o uso de estratégias colaborativas, como Pull Requests, traz ainda mais flexibilidade ao processo.
Se esse cenário já parece promissor, imagine reduzir o tempo de dias para horas.
Criando o C4 model de um projeto com a StackSpot AI
Para criar todos os diagramas, levei cerca de duas horas usando meu Quick Command de Geração de C4 Model. O passo mais complexo foi descrever o projeto, onde precisei apenas detalhar as tecnologias utilizadas e o objetivo claro que gostaria de atingir com o microsserviço.
Agora que já entendemos as principais características da StackSpot AI e a importância do C4 Model em um projeto de desenvolvimento, está na hora de ir para a parte prática.
Adicionando Knowledge Sources
Primeiramente, adicionei dois Knowledge Sources à minha conta na StackSpot AI. Uma estratégia ao criar suas fontes de conhecimento é pensar em como elas serão utilizadas.
1º Knowledge Source – Definição do C4 Model: Adicionei a definição do C4 Model e todas as suas camadas (System Context, Container, Component, UML, etc.). Basicamente, copiei todo o conteúdo do site oficial da documentação do C4 Model e adicionei manualmente na StackSpot AI.
Importante: Eu posso usar essa Knowledge Source sempre que desejar contextualizar sobre o C4 model em projetos futuros. Não é necessário repetir esse passo das próximas vezes.
2º Knowledge Source – Definição do Projeto:
Adicionei a definição do Projeto como um Knowledge Source utilizando o seguinte texto:
Projeto de Integração com API da Bankly para Geração de Boletos Bancários
Este projeto tem como objetivo desenvolver um microsserviço responsável pela integração entre o front-end e a API da Bankly, visando a geração de boletos bancários.
Tecnologias Definidas:
Linguagem: Java
Framework: Spring
Integrações Externas: OpenFeign para comunicação com sistemas externos
Banco de Dados: Relacional, utilizado para recuperar informações do usuário necessárias para a geração do boleto via integração
Monitoramento: Logs para acompanhamento e análise de eventos
Observabilidade: Grafana e Prometheus para monitoramento e métricas
Deploy: AWS EKS (Elastic Kubernetes Service) para orquestração e gerenciamento de containers
Essa estrutura garante uma solução robusta e escalável, com foco em integração eficiente e monitoramento contínuo.
Implementando o Quick Command
Agora entraremos na parte mais divertida: implementar o fluxo de trabalho de prompts de comandos, ou seja, criar o nosso Quick Command. No portal, basta clicar em “Quick Commands” e depois em “Create Custom Quick Commands” para iniciar a criação da sua automação.
Após passar por essa etapa, podemos criar nossos comandos e interligá-los para criar um fluxo de trabalho.
- Entendimento do Projeto: O primeiro prompt que criei foi nomeado como “entendimento-projeto”. Ele é responsável por pegar toda a definição do projeto, entender do que se trata, cobrir possíveis gaps de arquitetura, segurança e negócio, e, por último, criar toda uma documentação técnica com base em uma Stack que passei como comando.
Entrada: "{{selected_code}}"
Saída: "Compreenda o projeto acima, adicione qualquer passo de execução que esteja faltando, e defina uma stack de tecnologia incluindo as tecnologias citadas no contexto do projeto, e outras tecnologias necessárias."- Desenhos de Arquitetura: O segundo prompt trata-se de criar os desenhos de arquitetura do projeto, baseando-se nas definições do C4 Model e todas as suas respectivas camadas.
Entrada: "{{entendimento-projeto.answer}}"
Saída: "Com base na resposta acima, gere um modelo de arquitetura C4 no formato C4-PlantUML como referência, incluindo: um diagrama de System Context (nível 1), um diagrama de Container (nível 2), e um diagrama de Component (nível 3), tudo em português."
Executando o Quick Command no VS Code
Após instalar e conectar na extensão da StackSpot AI para o VS Code, você verá uma mensagem de confirmação.
Como personalizei o meu comando de entendimento do projeto para receber um “código selecionado”, copiei a descrição do micro serviço que precisa ser desenvolvido para uma nova aba do VSCode, selecionei todo o conteúdo e executei o comando.
Após aguardar a execução do fluxo de trabalho, obtive três diagramas, cada um contendo informações de um nível específico do padrão definido pelo C4 Model.
Resultado alcançado
Esses diagramas fornecem uma visão clara e detalhada da arquitetura do sistema, desde a interação com os usuários até a implementação interna dos componentes.
A seguir estão os diagramas de arquitetura C4 no formato Diagrama Mermaid e sua respectiva explicação:
1 – System Context Diagram (Nível 1)
Este diagrama mostra uma visão geral do sistema e suas interações com os atores externos. O usuário do front-end interage com o frontend para solicitar a geração de boletos. O microsserviço de geração de boletos processa essas requisições, recupera dados do banco de dados relacional e se comunica com a API da Bankly para gerar os boletos.
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_LEFT_RIGHT()
title System Context - Microsserviço de Geração de Boletos Bancários
Person(frontendUser, "Usuário do Frontend", "Usuário que interage com o sistema via frontend")
Person(banklyAPI, "API da Bankly", "API externa para geração de boletos bancários")
System_Boundary(system, "Microsserviço de Geração de Boletos") {
System(frontend, "Frontend", "Interface de usuário para solicitar a geração de boletos")
System(microservice, "Microsserviço de Geração de Boletos", "Microsserviço que processa as requisições e gera boletos")
SystemDb(database, "Banco de Dados Relacional", "Armazena dados do usuário e transações")
}
Rel(frontendUser, frontend, "Solicita geração de boletos")
Rel(frontend, microservice, "Envia requisição de geração de boletos")
Rel(microservice, banklyAPI, "Comunica-se com a API da Bankly para gerar boletos")
Rel(microservice, database, "Recupera dados do usuário e transações")
@enduml
2 – Container Diagram (Nível 2):
O diagrama de containers detalha os principais componentes do sistema. O front-end é implementado em React e se comunica com o microsserviço de geração de boletos desenvolvido em Spring Boot. O microsserviço se conecta a um banco de dados relacional (PostgreSQL) para recuperar dados e utiliza Prometheus e Grafana para monitoramento e visualização de métricas. O deploy é feito no AWS EKS para orquestração de containers.
@startuml
!define C4Container
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_LEFT_RIGHT()
Person(user, "Usuário", "Usuário final que interage com o front-end da aplicação")
Container(frontend, "Front-end", "React", "Interface do usuário para solicitar a geração de boletos")
System_Boundary(system, "Microsserviço de Geração de Boletos") {
Container(awseks, "Deploy", "AWS EKS", "Orquestrador de containers")
Container(prometheus, "Prometheus", "Prometheus", "Coleta informações das aplicações e envia para Grafana")
Container(microservice, "Microsserviço de Geração de Boletos", "Spring Boot", "Microsserviço que integra com a API da Bankly para gerar boletos")
ContainerDb(database, "Banco de Dados", "PostgreSQL", "Armazena informações dos usuários e boletos gerados")
ContainerDb(grafana, "Métricas", "Grafana", "Armazena informações de métricas da aplicação")
}
Container_Ext(api_bankly, "API da Bankly", "API externa", "API externa para geração de boletos bancários")
Rel(user, frontend, "Solicita a geração de boletos")
Rel(frontend, microservice, "Envia requisição para geração de boletos via HTTP")
Rel(microservice, api_bankly, "Integra com a API da Bankly via OpenFeign")
Rel(microservice, awseks, "Deploy da aplicação")
Rel(microservice, database, "Armazena e recupera informações dos usuários e boletos")
Rel(microservice, prometheus, "Envia métricas para prometheus")
Rel(prometheus, grafana, "Salva as informações no grafana")
@enduml
3 – Component Diagram (Nível 3):
O diagrama de componentes foca no microsserviço de geração de boletos. Ele é composto por:
- BoletoController: Um controlador REST que recebe as requisições do frontend.
- BoletoService: Um serviço que contém a lógica de geração de boletos.
- BanklyFeignClient: Um cliente Feign que se comunica com a API da Bankly.
- UserRepository: Um repositório JPA que acessa os dados do banco de dados.
- PrometheusMetrics: Um componente que coleta métricas e as envia para o Prometheus.
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
LAYOUT_LEFT_RIGHT()
title System Context - Microsserviço de Geração de Boletos Bancários
Container_Boundary(microservice, "Microsserviço de Geração de Boletos") {
Component(controller, "BoletoController", "Spring REST Controller", "Recebe requisições do frontend")
Component(service, "BoletoService", "Spring Service", "Processa a lógica de geração de boletos")
Component(feignClient, "BanklyFeignClient", "OpenFeign Client", "Comunica-se com a API da Bankly")
Component(repository, "UserRepository", "JPA Repository", "Acessa dados do usuário no banco de dados")
Component(prometheusMetrics, "PrometheusMetrics", "Prometheus", "Coleta métricas do microsserviço")
}
Rel(controller, service, "Chama o serviço para processar a geração de boletos")
Rel(service, feignClient, "Usa Feign Client para se comunicar com a API da Bankly")
Rel(service, repository, "Recupera dados do usuário e transações")
Rel(service, prometheusMetrics, "Envia métricas para Prometheus")
@endumlConclusão
Combinando o C4 Model com a StackSpot AI, é possível construir e documentar arquiteturas de software de maneira rápida e precisa.
O C4 Model oferece uma visão clara em diferentes níveis de abstração, facilitando a comunicação entre equipes técnicas e de negócios. Por sua vez, a StackSpot AI potencializa essa modelagem ao automatizar a criação e organização de diagramas, otimizando o tempo gasto em tarefas repetitivas, reduzindo o trabalho manual e garantindo maior consistência nos projetos.
Juntas, essas abordagens resultam em soluções escaláveis, bem documentadas e fáceis de gerenciar, promovendo agilidade e qualidade no desenvolvimento de software.
O que achou deste tutorial de como criar um C4 Model com a StackSpot AI? Conte pra gente nos comentários!
