☠️ tiffs.dev

diagramas arquiteturais

leitura de 5 min

a representação visual de arquiteturas é essencial para discutir e apresentar soluções técnicas. a escolha do diagrama e seu nível de detalhamento deve sempre considerar o público-alvo e o objetivo da comunicação.

padrões formais de diagramação

UML (Unified Modeling Language)

surgiu para unificar a modelagem de sistemas. embora extenso, os diagramas mais utilizados hoje são:

diagrama de classes (estrutura estática)

é o diagrama mais fundamental da UML. representa a estrutura do sistema, não o que acontece ao longo do tempo. seus principais elementos são:

  • classes: os retângulos (Cliente, Pedido)
  • atributos: as variáveis/dados (nome, data etc). é usada a notação + para atributos públicos e - para atributos privados
  • métodos: as funções de cada classe (fazerLogin(), calcularTotal())
  • relações: as linhas que conectam as classes (realiza, ex: Cliente tem 1 para muitos (*) Pedidos)
classDiagram
    Cliente "1" --> "*" Pedido : realiza
    
    class Cliente {
        +String nome
        -String cpf
        +fazerLogin()
    }
    
    class Pedido {
        +Integer id
        +Date data
        +adicionarItem()
        +fecharPedido()
    }

diagrama de sequência (comportamento dinâmico)

foca na interação e na ordem dos eventos, mostrando a troca de informações entre os componentes ao longo do tempo. seus principais elementos são:

  • atores/participantes: quem está interagindo (Usuário, API, Banco de Dados etc)
  • lifelines: as linhas pontilhadas verticais. o tempo corre de cima para baixo
  • mensagens: setas que vão de uma linha à outra. seta cheia ( -->) significa requisição, seta pontilhada (-- ->) significa retorno.
sequenceDiagram
    autonumber
    participant U as Usuário
    participant F as Frontend
    participant A as API
    participant B as Banco de Dados
    
    U->>F: Clica em "Finalizar Compra"
    
    rect rgb(240, 248, 255)
    Note right of F: Início do fluxo transacional
    F->>A: POST /v1/checkout
    activate A
    
    A->>A: Valida Estoque
    A->>B: INSERT pedido
    B-->>A: Retorna ID (201)
    
    A-->>F: HTTP 201 Created
    deactivate A
    end
    
    F-->>U: Exibe "Sucesso"

C4 Model

criado para preencher as lacunas de visualização de arquitetura deixadas pela UML (com foco em código). propõe 4 níveis de abstração (zoom-in):

nível 1: context

é o nível mais alto, tem o objetivo de mostrar o big picture. representa o sistema inserido no ambiente, usuários e integrações externas.

C4Context
    title Diagrama de Contexto - Sistema de Vendas
    
    Person(cliente, "Cliente", "Pessoa que realiza compras online")
    Person(admin, "Administrador", "Gerencia o catálogo e pedidos")

    System(sistemaVendas, "Sistema de Vendas", "Permite comprar produtos e gerenciar pedidos")

    System_Ext(gatewayPagamento, "Gateway de Pagamento", "Processa os pagamentos (ex: Stripe, PayPal)")
    System_Ext(sistemaEmail, "Sistema de E-mail", "Envia confirmações para os clientes")

    Rel(cliente, sistemaVendas, "Visualiza produtos e faz compras", "HTTPS")
    Rel(admin, sistemaVendas, "Gerencia produtos", "HTTPS")
    Rel(sistemaVendas, gatewayPagamento, "Processa pagamentos", "API/HTTPS")
    Rel(sistemaVendas, sistemaEmail, "Envia e-mails", "SMTP")

nível 2: container

o objetivo é “dar um zoom” no sistema para mostrar as aplicações, APIs, bancos de dados etc que os compõem.

C4Container
    title Diagrama de Contêiner - Sistema de Vendas

    Person(cliente, "Cliente", "Pessoa que realiza compras")

    Container_Boundary(bSistemaVendas, "Sistema de Vendas") {
        Container(webApp, "Web App", "React/Next.js", "Interface principal para o cliente")
        Container(mobileApp, "Mobile App", "Flutter", "App para compras via celular")
        Container(api, "API Backend", "Java/Spring Boot", "Lógica de negócios e orquestração")
        ContainerDb(database, "Banco de Dados", "PostgreSQL", "Armazena pedidos, clientes e catálogo")
    }

    System_Ext(gatewayPagamento, "Gateway de Pagamento", "Processa pagamentos")

    Rel(cliente, webApp, "Visita", "HTTPS")
    Rel(cliente, mobileApp, "Usa", "HTTPS")
    
    Rel(webApp, api, "Chama", "JSON/HTTPS")
    Rel(mobileApp, api, "Chama", "JSON/HTTPS")
    
    Rel(api, database, "Lê e Escreve", "JDBC")
    Rel(api, gatewayPagamento, "Processa transações", "API/HTTPS")

nível 3: componente

é opcional, e entra nos detalhes internos de um container, para mostrar sua estrutura (por exemplo, os controllers, services e repositories de uma API).

C4Component
    title Diagrama de Componentes - API Backend

    Container(webApp, "Web App", "React", "Envia requisições")
    ContainerDb(database, "Banco de Dados", "PostgreSQL", "Persistência")

    Container_Boundary(api, "API Backend") {
        Component(signController, "Sign In Controller", "Spring MVC", "Gerencia autenticação e tokens")
        Component(compraController, "Compra Controller", "Spring MVC", "Recebe requisições de compra")
        Component(seguranca, "Componente de Segurança", "Spring Security", "Valida permissões")
        Component(pagamentoService, "Serviço de Pagamento", "Classe Java", "Regras de negócio de pagamento")
        Component(repositorio, "Repositório de Pedidos", "JPA/Hibernate", "Abstração do banco de dados")
    }

    Rel(webApp, signController, "Faz login", "JSON/HTTPS")
    Rel(webApp, compraController, "Envia pedido", "JSON/HTTPS")

    Rel(signController, seguranca, "Usa")
    Rel(compraController, seguranca, "Usa")
    Rel(compraController, pagamentoService, "Chama")
    Rel(pagamentoService, repositorio, "Salva dados")
    
    Rel(repositorio, database, "SQL", "JDBC")

nível 4: código

é opcional e pouco usado. não tem notação específica, ficando livre para usar qual quiser (UML, por exemplo).

abordagens ad hoc

nem todo diagrama precisa seguir um padrão, como UML ou C4. em diagramas com propósitos específicos, é possível usar abordagens ad hoc, desde que sejam claros e atendam ao objetivo da arquitetura.

diagrama precisa de objetivo de acordo com a proposta nem todo diagrama precisa seguir um padrão → diagramas ad hoc (para propósitos específicos que podem substituir os padrões, desde que sejam claros e atendam ao objetivo da arquitetura)

diagramas de baixa fidelidade

podem ser usados no início do esboço de uma arquitetura (boards, desenhos etc), como representações simples e temporárias. permite maior flexibilidade e estimula a colaboração.

guidelines para uma boa diagramação

para reduzir a carga cognitiva (keep it simple) e garantir o entendimento, é necessário que o diagrama tenha::

  • clareza e coesão, sendo capaz de contar a história da estrutura
  • títulos claros nos diagramas e nomes descritivos nos componentes
  • conexões bem definidas (direção do fluxo)
  • consistência, mantendo um padrão visual sem variar estilos
  • uso de cores para diferenciar tipos de elementos (ex: azul para interno, cinza para externo), não apenas para estética
  • legendas para decodificar símbolos e cores

⚠️ anti-padrão: apego irracional ao artefato

ocorre quando o profissional defende um diagrama impreciso só porque investiu muito tempo criando-o.

"quanto mais tempo e esforço você investir no planejamento ou em um documento, maior será a probabilidade de você proteger o que está contido no plano ou documento, mesmo diante de evidências de que ele é impreciso ou desatualizado." — Neal Ford

ferramentas

visão de gráfico

backlinks