Guia de Referência: Clean Architecture (Robert C. Martin)

Este guia consolida os princípios, regras de dependência e limites arquiteturais propostos por Robert C. Martin ("Uncle Bob") no livro Arquitetura Limpa: O Guia do Artesão para Estrutura e Design de Software.

1. O Princípio Fundamental: A Regra de Dependência

"As dependências de código-fonte devem apontar apenas para dentro, na direção dos códigos de alto nível (políticas de negócio)."

Nada em um círculo interno pode saber algo sobre algo em um círculo externo. Nomes de formatos de dados, bancos de dados, frameworks ou UI declarados em um círculo externo não devem ser mencionados pelo código em um círculo interno.

2. As Camadas do Sistema

1ª Camada: Entidades (Entities / Domain Core)

• O que contém: Objetos de negócio e regras corporativas mais gerais e de alto nível. Encapsula os dados e os comportamentos centrais.
• Regra de Ouro: Não conhecem banco de dados, frameworks, UI ou ferramentas de rede. São puras. Mudanças em detalhes externos (como migrar de ORM ou banco de dados) nunca afetam essa camada.
• Componentes: Entities, Value Objects, Domain Services, Domain Exceptions.

2ª Camada: Casos de Uso (Use Cases / Application Business Rules)

• O que contém: Regras de negócio específicas da aplicação. Orquestra o fluxo de dados vindos e direcionados para as entidades, direcionando-as para alcançar os objetivos do caso de uso.
• Regra de Ouro: Isolada de mudanças na UI ou de escolhas de persistência. Contém interfaces (Ports/Abstrações) para os dados necessários.
• Componentes: Use Case Interactors, Input Ports (DTOs de entrada), Output Ports (Interfaces de Repositories/Gateways, DTOs de saída).

3ª Camada: Adaptadores de Interface (Interface Adapters / Presenters / Controllers)

• O que contém: Tradutores de dados. Converte os dados no formato mais conveniente para os casos de uso e entidades, para o formato mais conveniente para agentes externos (como Web, BD, Dispositivos).
• Regra de Ouro: É onde ficam os controladores de APIs, presenters de UI, e as implementações abstratas de acesso a dados (Mappers, Query Builders).
• Componentes: Controllers (REST/GraphQL), Presenters, ViewModels, Gateways, DB Repositories Concretos.

4ª Camada: Frameworks e Drivers (Frameworks & Drivers / Infrastructure)

• O que contém: Onde residem os detalhes técnicos. O banco de dados (PostgreSQL, Supabase), a interface do usuário (Flutter, HTML/CSS), a biblioteca de rotas, ferramentas de terceiros.
• Regra de Ouro: Contém apenas código de colagem (glue code) para interligar a infraestrutura aos adaptadores. Deve ser tratada como um mero plug-in do sistema.
• Componentes: Configurações de Bancos de Dados, Drivers de Redes, Inicializadores de Frameworks, UI Widgets.

3. Princípios de Design Componentizados (SOLID aplicado à Arquitetura)

• SRP (Single Responsibility Principle): Um módulo deve ter apenas uma razão para mudar (deve responder a apenas um ator). Separe o cálculo de negócio do mecanismo de exibição/armazenamento.
• OCP (Open-Closed Principle): Um artefato de software deve estar aberto para extensão, mas fechado para modificação. Conseguido dividindo o sistema em componentes e ordenando as dependências de forma que as mudanças nos componentes de baixo nível (ex: UI) não alterem os de alto nível (ex: Domínio).
• LSP (Liskov Substitution Principle): As subclasses/implementações devem ser intercambiáveis pelas suas classes base/interfaces sem quebrar o comportamento esperado do sistema.
• ISP (Interface Segregation Principle): Evite depender de módulos que contenham métodos não utilizados. Crie interfaces granulares e focadas no cliente (ex: não faça um repositório gigantesco se o caso de uso só precisa ler uma linha).
• DIP (Dependency Inversion Principle): Módulos de alto nível não devem depender de módulos de baixo nível. Ambos devem depender de abstrações. (Mecanismo usado para fazer a infraestrutura obedecer ao Domínio).

4. Cruzando as Fronteiras (Polimorfismo e DTOs)

1. Inversão de Controle: Quando um Caso de Uso precisa chamar o Banco de Dados (Infraestrutura), ele define uma Interface (Output Port) na camada de Caso de Uso. A camada de Infraestrutura implementa essa interface. Assim, o fluxo de controle vai para fora, mas a dependência de código aponta para dentro.
2. Isolamento de Dados (DTOs): Os dados que cruzam os limites das camadas devem ser estruturas simples de dados (Data Transfer Objects). Nunca passe entidades de domínio ou registros/modelos de banco de dados diretos (como objetos ORM) através das fronteiras.

Diretrizes de Execução Estrutural

Ao criar ou reestruturar arquivos, garanta:

1. Independência de Framework: O núcleo do software não deve depender de recursos de bibliotecas de terceiros.
2. Testabilidade: As regras de negócio devem ser testáveis sem a presença de UI, Banco de Dados, Servidores Web ou qualquer elemento externo.
3. Independência da UI: A UI pode mudar facilmente sem alterar o resto do sistema.
4. Independência do Banco de Dados: Você pode trocar o mecanismo de persistência por outro sem tocar em uma única linha de regras de negócio.

Guia de Referência: Padrões de Projeto (Design Patterns)

Este guia serve como base conceitual e prática para a aplicação de soluções consolidadas para problemas recorrentes no desenvolvimento de software orientada a objetos (GOF - Gang of Four).

1. Padrões Criacionais (Creational Patterns)

Focam no processo de criação de objetos, abstraindo a lógica de instanciação e tornando o sistema independente de como seus objetos são criados, compostos e representados.

Factory Method

• Intenção: Define uma interface para criar um objeto, mas deixa as subclasses decidirem qual classe instanciar.
• Estrutura de Aplicação: Utilizar quando o código não deve conhecer a classe exata e dependências dos objetos com os quais precisa operar.
• Regra de Design: Depender de abstrações e não de implementações concretas (DIP).

Abstract Factory

• Intenção: Permite produzir famílias de objetos relacionados ou dependentes sem especificar suas classes concretas.
• Estrutura de Aplicação: Fornece interfaces para criação de cada componente de uma suite/família de produtos.

Builder

• Intenção: Permite a construção de objetos complexos passo a passo. O padrão permite produzir diferentes tipos e representações de um objeto usando o mesmo código de construção.
• Estrutura de Aplicação: Utilizar para construção de entidades de domínio complexas com múltiplos parâmetros opcionais ou configurações ricas.

Singleton

• Intenção: Garante que uma classe tenha apenas uma instância e fornece um ponto de acesso global a ela.
• Aviso de Arquitetura: Usar com extrema cautela, pois introduz estado global oculto e pode dificultar testes unitários. Preferir injeção de dependência via container.

2. Padrões Estruturais (Structural Patterns)

Focam em como classes e objetos são compostos para formar estruturas maiores, garantindo que as partes do sistema permaneçam flexíveis e eficientes.

Adapter

• Intenção: Permite que objetos com interfaces incompatíveis colaborem entre si.
• Estrutura de Aplicação: Essencial na Arquitetura Limpa para converter os dados dos Repositories/Gateways externos para o formato exigido pelas entidades ou casos de uso da aplicação.

Composite

• Intenção: Permite compor objetos em estruturas de árvore para representar hierarquias partes-todo. Permite que clientes tratem objetos individuais e composições de objetos de maneira uniforme.

Decorator

• Intenção: Permite adicionar novos comportamentos a objetos dinamicamente, colocando-os dentro de objetos envoltórios (wrappers) que contêm esses comportamentos.
• Estrutura de Aplicação: Adicionar responsabilidades como caching, log, ou validação cross-cutting sem modificar as classes de regra de negócio originais.

Facade

• Intenção: Fornece uma interface unificada para um conjunto de interfaces em um subsistema. Define uma interface de nível mais alto que torna o subsistema mais fácil de usar.
• Estrutura de Aplicação: Simplificar a interação do domínio com subsistemas legados complexos ou bibliotecas externas de terceiros.

Proxy

• Intenção: Fornece um substituto ou marcador de posição para outro objeto para controlar o acesso a ele, atrasar sua criação ou realizar auditorias de segurança.

3. Padrões Comportamentais (Behavioral Patterns)

Focam nos algoritmos, na atribuição de responsabilidades entre objetos e em como eles se comunicam.

Chain of Responsibility

• Intenção: Permite passar solicitações ao longo de uma cadeia de manipuladores. Ao receber uma solicitação, cada manipulador decide se processa a solicitação ou a passa para o próximo manipulador na cadeia.

Command

• Intenção: Transforma uma solicitação em um objeto autônomo que contém todas as informações sobre a solicitação. Essa transformação permite parametrizar métodos com diferentes solicitações.

Iterator

• Intenção: Permite percorrer elementos de uma coleção sem expor sua representação subjacente (lista, pilha, árvore, etc.).

Mediator

• Intenção: Permite reduzir as dependências caóticas entre objetos. O padrão restringe as comunicações diretas entre os objetos e os força a colaborar apenas através de um objeto mediador.
• Estrutura de Aplicação: Comum na camada de Application para desacoplar handlers de eventos e controllers (ex: biblioteca MediatR ou padrões de Event Bus internos).

Observer

• Intenção: Define um mecanismo de assinatura para notificar múltiplos objetos sobre quaisquer eventos que aconteçam com o objeto que eles estão observando.
• Estrutura de Aplicação: Disparo de eventos de domínio (Domain Events) após a execução bem-sucedida de um Caso de Uso.

State

• Intenção: Permite que um objeto altere seu comportamento quando seu estado interno muda. O objeto parecerá ter mudado de classe.
• Estrutura de Aplicação: Ideal para modelar fluxos de ciclo de vida complexos dentro de Entidades de Domínio (ex: status de um pedido, aprovações de folhas de ponto).

Strategy

• Intenção: Define uma família de algoritmos, encapsula cada um deles e os torna intercambiáveis. Permite que o algoritmo varie independentemente dos clientes que o utilizam.
• Estrutura de Aplicação: Regras de cálculo variáveis (como regras de horas extras, adicionais de folha de pagamento, impostos) injetadas dinamicamente conforme o contexto.

Template Method

• Intenção: Define o esqueleto de um algoritmo na superclasse, mas deixa as subclasses sobrescreverem etapas específicas do algoritmo sem modificar sua estrutura estrutural.

Checklist de Aplicação nos Projetos

1. Evite Overengineering: Não force padrões onde um design simples resolve. Aplique padrões quando houver variação legítima ou complexidade de manutenção.
2. Casamento com Princípios: Use Padrões Criacionais junto ao OCP (Open-Closed Principle) para estender sistemas sem modificar o código existente.
3. Desacoplamento de Infraestrutura: Use Adapters e Strategies para isolar o domínio das escolhas tecnológicas mutáveis.