Como transformar requisitos escritos em linguagem natural em uma arquitetura de software sólida e comunicável?
Este material didático percorre o caminho completo: da dissecação de requisitos em substantivos e verbos, passando pela anatomia de classes UML e seus relacionamentos, até a aplicação do C4 Model como ferramenta de comunicação arquitetural em diferentes níveis de abstração. Baseado na aula do Prof. Alexandre Gomes (UDF), o conteúdo integra conceitos de modelagem orientada a objetos com práticas modernas de documentação de arquitetura.
A engenharia de software enfrenta um desafio perene: traduzir requisitos de negócio — escritos em linguagem natural, ambíguos e focados no problema — em código-fonte, que é rígido, determinístico e focado na solução. Sem um modelo intermediário que funcione como ponte entre esses dois mundos, a tradução direta frequentemente produz falhas de arquitetura que se propagam por todo o ciclo de vida do sistema (LARMAN, 2004). A disciplina de modelagem estrutural existe precisamente para preencher esse abismo, oferecendo abstrações visuais que não são o sistema final, mas constituem o mapa vital para construí-lo sem desvios.
Este artigo detalha o percurso metodológico apresentado na disciplina de Modelagem Estrutural de Soluções, que organiza a tradução de requisitos em quatro etapas progressivas: a construção do mapa de domínio a partir do texto bruto, a formalização em classes UML com atributos e relações, o encapsulamento em componentes escaláveis, e, por fim, a comunicação da arquitetura resultante por meio do C4 Model em diferentes níveis de abstração (BROWN, 2018).
O mapa de domínio — também chamado de modelo de domínio ou modelo conceitual — é o primeiro artefato visual produzido nesse percurso. Trata-se de uma representação gráfica dos conceitos-chave de um domínio de negócio, seus atributos essenciais e os relacionamentos entre eles, sem nenhum compromisso com detalhes de implementação. Diferentemente de um diagrama de classes técnico, o mapa de domínio utiliza o vocabulário do próprio negócio: se os usuários falam em "paciente", "consulta" e "prontuário", são exatamente esses os termos que aparecem no mapa. Seu propósito é criar um entendimento compartilhado entre analistas, desenvolvedores e stakeholders antes que qualquer decisão de arquitetura seja tomada (LARMAN, 2004). É, em essência, a fotografia do "universo do problema" que antecede o "universo da solução".
1 O abismo entre o negócio e o código
Considere um requisito típico: "precisa calcular frete baseado em peso e destino". Essa frase, perfeitamente compreensível para um analista de negócios, carrega ambiguidades que o código não tolera: o que é "frete"? É uma entidade, um cálculo, ou ambos? "Peso" refere-se a gramas, quilogramas ou libras? "Destino" é uma string, um objeto complexo com coordenadas geográficas, ou uma referência a uma tabela de CEPs?
Do lado oposto, o código-fonte correspondente — uma classe CalculadoraDeFrete com um método calcular(peso: Peso, destino: Destino): Valor — é preciso demais para ser discutido com stakeholders não técnicos. O analista de negócios pergunta "como calcula o frete?"; o desenvolvedor responde com tipos, parâmetros e retornos. Essa assimetria não é um defeito de comunicação: é uma propriedade intrínseca dos dois domínios. Requisitos em linguagem natural são, por definição, ambíguos, informais e focados no problema; código-fonte é, por construção, rígido, determinístico e focado na solução (LARMAN, 2004).
A modelagem estrutural propõe um vocabulário intermediário — diagramas e notações formais — que permite a ambas as partes (negócio e engenharia) convergirem para um entendimento compartilhado antes que uma linha de código seja escrita.
2 Dissecação de requisitos: substantivos e verbos
A primeira técnica concreta para construir o mapa de domínio é a análise linguística de requisitos — a chamada "análise nome-verbo" (LARMAN, 2004). O modelador percorre os textos de requisitos, casos de uso e entrevistas com stakeholders, sublinhando dois grupos gramaticais distintos. Tomando como exemplo a frase "o paciente (cão ou gato) precisa agendar uma consulta com o veterinário, que prescreve medicamentos":
Os substantivos — paciente, consulta, veterinário — são candidatos a entidades no mapa de domínio, isto é, retângulos com nome e atributos que representam conceitos do negócio. Os verbos — agendar, prescrever — são candidatos a associações (linhas de relacionamento entre entidades) ou a operações futuras quando o mapa evoluir para classes UML. O resultado dessa varredura é o rascunho inicial do mapa de domínio: um diagrama com as entidades identificadas, conectadas por relacionamentos nomeados a partir dos verbos encontrados.
Contudo, nem todo substantivo se torna uma classe, nem todo verbo se torna um método. É necessário filtrar sinônimos e falsas entidades: "medicamento", no contexto acima, pode ser apenas um atributo textual de uma prescrição, e não uma classe complexa com comportamento próprio. A regra fundamental é: se o conceito possui atributos independentes e comportamento que justifique encapsulamento, ele é uma classe; caso contrário, é um atributo de outra classe ou simplesmente um valor (LARMAN, 2004).
3 Anatomia de uma classe UML
Uma vez identificadas as entidades do domínio, cada uma é formalizada como uma classe UML, composta por três compartimentos. O primeiro contém o nome da classe, que representa o conceito do domínio e é sempre um substantivo (por exemplo, Consulta). O segundo compartimento lista os atributos — o estado interno do objeto —, cada um com seu modificador de visibilidade e tipo: - dataHora: DateTime indica um atributo privado, enquanto + status: String indica um atributo público. O terceiro compartimento apresenta as operações — o comportamento do objeto —, derivadas dos verbos identificados nos requisitos: + confirmar(): void e # remarcar(): bool (FOWLER, 2003).
Os modificadores de visibilidade seguem a notação padronizada pela UML: + para público (public), - para privado (private) e # para protegido (protected). Essa notação implementa diretamente o princípio de encapsulamento: atributos devem ser ocultos por padrão (privados), expondo apenas a interface pública estritamente necessária (FOWLER, 2003).
4 Relacionamentos UML: a matriz de diagnóstico
Classes não existem isoladamente — elas se relacionam. A UML define quatro tipos fundamentais de relacionamento, cada um respondendo a uma pergunta diagnóstica específica, conforme sistematizado na tabela a seguir.
| Tipo | Símbolo | Pergunta diagnóstica | Exemplo prático | Por quê? |
|---|---|---|---|---|
| Associação | —— | Eles apenas interagem? | Professor — Aluno | Um professor leciona para alunos, mas ambos existem e vivem de forma completamente independente. |
| Agregação | ◇—— | O todo existe sem a parte? | Universidade ◇— Professor | A universidade reúne professores, mas se ela fechar, os professores continuam existindo como profissionais. |
| Composição | ◆—— | A parte morre se o todo morrer? | Pedido ◆— ItensDoPedido | Os itens só existem dentro de um pedido. Se o pedido for excluído, seus itens perdem totalmente o sentido. |
| Herança | △ | É um subtipo específico? | Pagamento ◁— Pix, Boleto, Cartão | Pix, Boleto e Cartão são formas específicas de Pagamento, compartilhando atributos comuns mas com comportamentos distintos. |
Fonte: Elaboração própria com base em Fowler (2003) e Larman (2004).
A distinção entre agregação e composição merece atenção especial. Na agregação, a parte pode existir independentemente do todo: se uma universidade fechar, os professores continuam existindo como profissionais e podem lecionar em outra instituição. Na composição, a parte não tem sentido fora do todo: se um pedido for cancelado e removido do sistema, os itens daquele pedido específico perdem sua razão de existir — eles não migram para outro pedido. Essa diferença semântica tem implicações diretas no código, determinando se a exclusão de um objeto deve ou não propagar-se em cascata para seus objetos relacionados (FOWLER, 2003).
5 Aumentando a escala: encapsulamento em componentes
À medida que o sistema cresce, o diagrama de classes se torna impraticável como ferramenta de comunicação. Dezenas de classes interconectadas geram alto acoplamento visual e cognitivo — o que a literatura chama de "diagrama espaguete" (BROWN, 2018). A solução é agrupar classes relacionadas em componentes, que atuam como caixas-pretas: ocultam a complexidade interna e expõem apenas interfaces providas (o que o componente oferece) e interfaces requeridas (o que o componente precisa de outros componentes).
Três heurísticas orientam o agrupamento de classes em componentes:
A coesão funcional determina que se deve agrupar o que muda junto. Classes que participam do mesmo processo de negócio — como Carrinho, Pedido e Pagamento — pertencem ao mesmo módulo. A inversão de dependência estabelece que regras de negócio não devem depender de detalhes de infraestrutura; ambos devem depender de abstrações (interfaces). E os bounded contexts, conceito oriundo do Domain-Driven Design, delimitam fronteiras de domínio: o conceito de "Produto" no contexto de Estoque difere semanticamente do "Produto" no contexto de Faturamento, e cada componente deve manter seu próprio vocabulário consistente (BROWN, 2018).
6 O paradoxo da comunicação arquitetural
Mesmo com componentes bem definidos, persiste um problema fundamental: o público que precisa entender a arquitetura não é homogêneo. Um diagrama de classes detalhado, perfeito para um desenvolvedor sênior, é ilegível para um diretor de negócios. Por outro lado, um diagrama de alto nível, adequado para o diretor, é inútil para quem vai efetivamente codificar o sistema.
O C4 Model, criado por Simon Brown, resolve esse paradoxo com uma abordagem baseada em níveis de abstração que adapta a mensagem ao público-alvo sem perder o rigor técnico. A sigla C4 refere-se aos quatro níveis: Context, Containers, Components e Code (BROWN, 2018).
7 C4 Model: o zoom da arquitetura
A analogia mais didática para o C4 Model é a de um mapa geográfico com zoom progressivo. O nível 1 (Contexto) corresponde ao "país": mostra o sistema como uma caixa-preta interagindo com usuários e sistemas externos. O nível 2 (Contêineres) corresponde à "cidade": revela as aplicações, APIs e bancos de dados que compõem e executam o sistema. O nível 3 (Componentes) corresponde ao "bairro": detalha os módulos internos dentro de cada contêiner. O nível 4 (Código) corresponde à "planta baixa": apresenta o nível microscópico de classes UML.
É fundamental compreender que C4 e UML são complementares, não concorrentes. O C4 Model utiliza a UML como notação nos níveis mais detalhados (especialmente no nível 4), enquanto nos níveis superiores adota uma notação própria, mais simples e acessível a públicos não técnicos (BROWN, 2018).
| Nível (escopo) | Público-alvo | Pergunta que responde |
|---|---|---|
| Nível 1: Contexto | Stakeholders e C-Level | Quem usa o sistema e com quem ele se integra externamente? |
| Nível 2: Contêineres | Arquitetos e devs seniores | Quais são as peças de software implantáveis e como se comunicam? |
| Nível 3: Componentes | Equipes de desenvolvimento | Como a API é estruturada internamente em módulos funcionais? |
| Nível 4: Código (UML) | Desenvolvedores | Como as classes e interfaces são implementadas no nível do código? |
Fonte: Elaboração própria com base em Brown (2018).
8 C4 na prática: contexto e contêineres
No nível 1 (visão executiva), o diagrama de contexto mostra, por exemplo, um "Sistema de Clínica" como uma única caixa azul, com um ator "Cliente" à esquerda e um sistema externo "Gateway de Pagamento" à direita. Nenhum detalhe interno é revelado — e esse é precisamente o ponto. Um CEO ou investidor precisa entender o que o sistema faz e com quem ele interage, não como ele faz internamente.
No nível 2 (visão de implantação), o mesmo sistema é decomposto em seus contêineres: uma Web App e um Mobile App no front-end, uma API Application no back-end, e um banco de dados (Database) para persistência. As setas indicam a direção da dependência e o fluxo de dados. No C4, as caixas representam limites claros de responsabilidade, e as setas sempre indicam a direção da dependência ou fluxo de dados (BROWN, 2018).
9 C4 e UML: o ponto de interseção
O nível 3 (Componentes) do C4 Model mapeia os grandes blocos lógicos dentro de um contêiner. Num exemplo de API Application, os componentes poderiam ser Auth, Agendamento e Faturamento — cada um encapsulando um domínio funcional completo com suas classes internas.
O nível 4 (Código) é onde o C4 Model e a UML se encontram de forma explícita. Ao fazer zoom em um componente específico — como o módulo de Agendamento —, o diagrama resultante é um diagrama de classes UML convencional, mostrando, por exemplo, a classe AgendamentoController com seus métodos +agendar(data: Date, pacienteId: string): Agendamento e +verificarDisponibilidade(data: Date): boolean, a classe AgendamentoService com a lógica de negócio, e a interface IAgendamentoRepository definindo o contrato de persistência.
Uma observação prática importante: não é necessário modelar todo o sistema em nível de classes UML. O nível 4 deve ser reservado para os componentes centrais, complexos ou de alto risco. Os demais componentes ficam adequadamente documentados nos níveis C2 ou C3 (BROWN, 2018).
10 O fio condutor: rastreabilidade de ponta a ponta
O valor completo da modelagem estrutural só se realiza quando existe rastreabilidade de ponta a ponta: cada classe no diagrama de código (nível 4) deve poder ser rastreada até um componente (nível 3), que pertence a um contêiner (nível 2), que atende a um contexto de sistema (nível 1), que, por sua vez, responde a um requisito de negócio original.
Se uma classe existe no modelo de código mas não tem origem em nenhum requisito, ela representa escopo não autorizado — o que a literatura denomina gold plating: funcionalidades adicionadas pela equipe técnica sem demanda explícita do negócio. Todo elemento técnico deve justificar sua existência respondendo a um requisito de negócio (LARMAN, 2004).
11 Modelos são artefatos vivos
A arquitetura evolui conforme o negócio muda. Um modelo estático, criado uma vez e nunca atualizado, torna-se rapidamente desatualizado e pode induzir decisões equivocadas — transformando-se naquilo que se pode chamar de "código legado moral": documentação que existe apenas para satisfazer um processo burocrático, sem refletir a realidade do sistema.
A recomendação prática é manter os diagramas de alto nível (C1 e C2) sempre atualizados, pois são usados com frequência por audiências diversas, e gerar diagramas de baixo nível (C3 e C4) sob demanda, próximos ao código, onde ferramentas de engenharia reversa podem auxiliar na geração automática (BROWN, 2018).
Considerações finais
A modelagem estrutural de soluções não é um exercício acadêmico desconectado da prática de desenvolvimento. É a ponte disciplinada entre a intenção do negócio e a implementação técnica. O percurso apresentado — do mapa de domínio ao C4 Model passando pela UML — oferece um roteiro concreto para equipes que desejam comunicar arquitetura de forma eficaz, em múltiplos níveis de detalhe e para audiências distintas.
O ponto central a reter é que modelos são ferramentas de comunicação antes de serem ferramentas de projeto. Um diagrama que ninguém lê ou que todos interpretam de forma diferente é pior do que nenhum diagrama. A combinação do C4 Model com a UML — aproveitando a acessibilidade do primeiro e o rigor formal da segunda — representa atualmente uma das abordagens mais equilibradas para documentar e comunicar arquitetura de software em contextos ágeis.
Referências
BROWN, Simon. Software Architecture for Developers. Vol. 1 e 2. Leanpub, 2018. Disponível em: https://leanpub.com/visualising-software-architecture. Acesso em: 26 abr. 2026.
BROWN, Simon. The C4 Model for Visualising Software Architecture. c4model.com, [s.d.]. Disponível em: https://c4model.com/. Acesso em: 26 abr. 2026.
FOWLER, Martin. UML Distilled: a brief guide to the standard object modeling language. 3. ed. Boston: Addison-Wesley, 2003.
LARMAN, Craig. Applying UML and Patterns: an introduction to object-oriented analysis and design and iterative development. 3. ed. Upper Saddle River: Prentice Hall, 2004.
Fonte:
Visto no Brasil Acadêmico
Comentários