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.

rule1. 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.

subdirectory_arrow_right2. As Camadas do Sistema

subdirectory_arrow_right1ª 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.

school2ª 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).

subdirectory_arrow_right3ª 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.

subdirectory_arrow_right4ª 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.

account_tree3. 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).

subdirectory_arrow_right4. 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.

subdirectory_arrow_rightDiretrizes 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.

school5. Como Usar este Guia com IA

• Novo projeto: peça primeiro o mapa de camadas, casos de uso, portas e adaptadores antes de gerar infraestrutura.
• Projeto existente: identifique dependências que apontam para fora e proponha uma migração incremental.
• Integrações: faça o núcleo declarar contratos; SDKs, bancos, HTTP e frameworks ficam nos círculos externos.
• Testes: teste entidades e casos de uso sem rede, banco ou UI sempre que possível.
• Composição: concentre a escolha das implementações concretas no ponto de entrada/composição da aplicação.

schoolRoteiro de Uso Operacional com IA

1. Contextualize o projeto: informe domínio, stack, arquitetura atual, restrições e objetivo da mudança.
2. Selecione o recorte: diga qual princípio/capítulo deste guia deve orientar a tarefa; não aplique tudo ao mesmo tempo.
3. Peça diagnóstico antes do código: a IA deve identificar sintomas, riscos, dependências e alternativas.
4. Defina critérios de aceite: comportamento, testes, acessibilidade, performance, segurança ou operação conforme o tema.
5. Implemente incrementalmente: mudanças pequenas, reversíveis e verificadas.
6. Faça revisão final: peça à IA que confronte a solução com este guia e liste desvios deliberados.

smart_toyPrompt de aplicação

Use este guia como referência técnica para a tarefa abaixo.
Não copie regras mecanicamente. Primeiro diagnostique o problema e selecione apenas os princípios aplicáveis.
Mostre: (1) diagnóstico, (2) decisão, (3) implementação proposta, (4) testes/verificações, (5) trade-offs e (6) checklist final.

Contexto: [DESCREVA o sistema, stack, estado atual e cenário da mudança]
Objetivo: [DESCREVA o resultado esperado e o comportamento que deve existir]
Restrições: [DESCREVA limites de escopo, compatibilidade, segurança, prazo e o que não pode mudar]

schoolComo preencher os campos

• Contexto: descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente.
• Objetivo: descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar.
• Restrições: informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo.

lightbulbExemplo preenchido

Contexto: Aplicação web tem regras de cálculo dentro de controllers e objetos do ORM atravessando toda a aplicação.
Objetivo: Extrair um caso de uso de cálculo para o núcleo e definir portas/adaptadores para persistência sem alterar a experiência atual.
Restrições: O domínio não pode importar framework, ORM ou HTTP; migração incremental; manter API e esquema do banco nesta etapa.