Guia Extra: Engenharia de Software e Modelagem UML • Bloco 4: Comportamento e Arquitetura

🗺️ Mapa Conceitual do Capítulo

flowchart TD
    subgraph GOV["Governança e Documentação Arquitetural Viva"]
        C4["Modelo C4 (Simon Brown)\nAbstração Hierárquica por Níveis de Zoom"]
        ADR["Architecture Decision Records (ADR)\nHistórico de Decisões e Trade-offs Técnicos"]
        ARC["Framework arc42 (Starke & Hruschka)\nTemplate Canônico em 12 Seções"]
    end

    subgraph C4_LEVELS["As 4 Camadas de Zoom do C4"]
        L1["Nível 1: Contexto do Sistema\nUsuários, Fronteiras e Ecossistema Externo"]
        L2["Nível 2: Contêineres de Software\nAplicações Web, APIs, Workers e Bancos de Dados"]
        L3["Nível 3: Componentes de Aplicação\nMódulos, Serviços de Domínio e Adaptadores"]
        L4["Nível 4: Código e Classes\nDiagramas de Classes e Tabelas (Geralmente Automatizado)"]
    end

    subgraph ARC_PILLARS["Pilares do arc42 e Qualidade"]
        QAW["Cenários de Qualidade (SEI / ATAM)\nFonte · Estímulo · Ambiente · Resposta · Métrica"]
        XCONC["Conceitos Transversais\nSegurança, Observabilidade, Resiliência e Persistência"]
    end

    C4 --> C4_LEVELS
    ARC --> QAW
    ARC --> XCONC
    ADR -.->|Seção 9 do arc42| ARC
    C4 -.->|Seções 3 e 5 do arc42| ARC

    style GOV fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style C4_LEVELS fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style ARC_PILLARS fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

🔍 1. O Modelo C4: Abstração Hierárquica por Níveis de Zoom

Criado pelo arquiteto britânico Simon Brown, o Modelo C4 resolve a desconexão comum entre modelos conceituais abstratos e diagramas de caixas coloridas sem padronização. Ele estrutura a comunicação técnica como uma analogia ao Google Maps, permitindo transitar suavemente de uma visão continental (satélite) até a visualização de ruas e quarteirões.

As 4 Camadas Estruturais do C4

Nível C4 Escopo e Questão Respondida Elementos Centrais Público-Alvo Principal
1. Contexto (System Context) “O que o sistema faz e com quem ele se comunica no ecossistema?” Sistema em caixa única, atores humanos (personas) e sistemas corporativos externos integrados. Executivos, Product Managers, Engenheiros e Stakeholders de Negócio.
2. Contêineres (Containers) “Quais são as unidades de software executáveis e onde os dados residem?” Single Page Applications (SPA), APIs REST, filas/tópicos (Kafka), bancos de dados e buckets S3. Arquitetos, Engenheiros de Software e Equipes de Operações/SRE.
3. Componentes (Components) “Como um contêiner específico é internamente decomposto em módulos de negócio?” Controllers, Serviços de Domínio, Repositórios de Acesso a Dados e Gateways de terceiros. Desenvolvedores e Mantenedores diretos do microsserviço.
4. Código (Code) “Como os elementos do componente são construídos na sintaxe da linguagem?” Diagramas de Classes UML, interfaces, structs Go ou diagramas Entidade-Relacionamento. Engenheiros em momentos pontuais de refatoração ou engenharia reversa.

⚠️ Atenção Semântica Fundamental: No modelo C4, o termo Contêiner NÃO significa imagem Docker ou contêiner Linux OCI. Significa qualquer unidade de computação executável autônoma ou repositório de persistência que possua runtime próprio.

Regras de Ouro na Notação C4

  • Todo componente ou contêiner deve exibir explicitamente seu Nome, sua Tecnologia entre colchetes (ex.: [Go / Gin], [PostgreSQL 16]) e uma Frase de Responsabilidade concisa.
  • Toda linha de comunicação deve ser direcionada (flecha) e conter rótulo explicativo do dado trafegado junto ao protocolo de transporte (ex.: “Consulta histórico de empréstimos [HTTPS/JSON]”`).

📝 2. Architecture Decision Records (ADRs)

Um Architecture Decision Record (ADR) é um documento conciso em texto plano (geralmente Markdown) que captura formalmente uma decisão arquitetural significativa tomada pelo time, explicitando as forças conflitantes (forces), as opções descartadas e as compensações aceitas (trade-offs).

O Formato Canônico de Michael Nygard

# 0005. Adoção de PostgreSQL com Particionamento Nativo para Logs de Auditoria

## Status
Aceito (Data: 2026-03-15)

## Contexto
O volume de transações de circulação do SGB cresceu para 2 milhões de eventos mensais.
Precisamos de armazenamento compatível com conformidade LGPD que permita consultas analíticas rápidas
sem degradar o tempo de resposta das transações OLTP de balcão.
Avaliamos o MongoDB (NoSQL) e o Elasticsearch, porém o time já possui alta maturidade em SQL e
deseja manter integridade referencial estrita com a tabela de Leitores.

## Decisão
Adotaremos o PostgreSQL 16 utilizando particionamento de tabelas por intervalo mensal (RANGE)
na entidade `AuditoriaEvento`, com índices BRIN sobre os timestamps.

## Consequências
- Positivas: Elimina a introdução de uma nova tecnologia no stack; preserva transações ACID; redução do custo de licença/nuvem.
- Negativas: Requer a criação de uma rotina automatizada (pg_partman ou cron) para pré-criação de partições futuras.
- Neutras: As consultas que cruzam mais de 12 meses exigirão agregação consciente via views materializadas.

Ciclo de Vida e Imutabilidade

  • Os estados canônicos de uma decisão são: Proposed, Accepted, Rejected, Deprecated ou Superseded by ADR-NNN.
  • Regra de Ouro da Governança: Um ADR aceito nunca é editado para refletir novas mudanças de rumo. Se a arquitetura mudar, cria-se um novo ADR (ex.: ADR-0012) que revoga o anterior, atualizando o status do documento original para “Substituído por ADR-0012”.

📚 3. O Framework arc42 para Arquitetura de Software

Concebido pelos pioneiros alemães Dr. Gernot Starke e Dr. Peter Hruschka, o arc42 é o template de documentação arquitetural mais adotado globalmente. Ele fornece uma estrutura pragmática composta por 12 seções complementares, que podem ser adotadas incrementalmente de acordo com a criticidade do sistema:

  1. Introdução e Metas: Objetivos de negócio do sistema, stakeholders e requisitos funcionais de primeira ordem.
  2. Restrições Arquiteturais: Limitações orçamentárias, tecnológicas, legais (LGPD) e organizacionais inegociáveis.
  3. Contexto e Escopo: Fronteiras do sistema, contexto de negócio e técnico (perfeito para C4 Nível 1).
  4. Estratégia de Solução: Princípios de design, padrões de arquitetura (ex.: Hexagonal, Clean, Microsserviços).
  5. Visão de Blocos de Construção: Decomposição estática hierárquica (C4 Níveis 2 e 3 e Diagramas de Componentes).
  6. Visão de Tempo de Execução: Dinâmica comportamental entre os blocos (Diagramas de Sequência e Atividades).
  7. Visão de Implantação: Topologia física de servidores, nuvem e conectividade (Diagrama de Implantação UML).
  8. Conceitos Transversais: Segurança (RBAC, JWT), Observabilidade (OpenTelemetry), Persistência e Tratamento de Erros.
  9. Decisões Arquiteturais: Catálogo consolidado com links diretos para as ADRs do repositório.
  10. Requisitos de Qualidade: Matriz formal de árvores de qualidade e cenários verificáveis.
  11. Riscos e Dívidas Técnicas: Análise de vulnerabilidades, pontos de falha única (SPOF) e planos de mitigação.
  12. Glossário: Dicionário da Linguagem Ubíqua para alinhar terminologia de engenheiros e especialistas de domínio.

🎯 4. Cenários de Qualidade Formais (SEI / ATAM)

No arc42 (Seção 10), requisitos não funcionais deixam de ser adjetivos vazios (como “o sistema deve ser rápido”) e transformam-se em cenários de teste mensuráveis baseados na metodologia ATAM (Architecture Tradeoff Analysis Method) do Software Engineering Institute (SEI):

\[\text{Fonte do Estímulo} \longrightarrow \text{Estímulo} \longrightarrow \text{Ambiente} \longrightarrow \text{Artefato} \longrightarrow \text{Resposta} \longrightarrow \text{Métrica}\] 
flowchart LR
    F["Fonte:\n2.000 Alunos"] -->|Dispara| E["Estímulo:\nRenovação Concorrente"]
    E --> A["Ambiente:\nPrimeiro dia letivo\n(Pico de Carga)"]
    A --> ART["Artefato:\nAPI de Circulação\ne Banco Relacional"]
    ART --> R["Resposta:\nProcessa sem falhas\nde concorrência"]
    R --> M["Métrica:\np99 < 350ms\nErro HTTP < 0.01%"]

    style F fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
    style ART fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style M fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

Essa formulação permite transformar requisitos arquiteturais em testes automatizados de performance (k6, Locust) e caos (Chaos Mesh) na esteira de CI/CD.