Você já entrou em um projeto e sentiu que mexer em qualquer coisa poderia quebrar tudo? Esse é o sinal claro de que a arquitetura precisava de mais atenção. É exatamente isso que a Clean Architecture resolve.
O que é Clean Architecture?
Clean Architecture é um modelo de organização de software criado por Robert C. Martin — o famoso Uncle Bob, o mesmo autor dos princípios SOLID que vimos no post anterior.
A ideia central é simples: separar as responsabilidades do seu sistema em camadas, de forma que o núcleo da sua aplicação — as regras de negócio — não dependa de nada externo. Nem do banco de dados, nem do framework, nem da interface do usuário.
Parece óbvio, mas a maioria dos projetos faz exatamente o contrário.
A metáfora da cebola
Pensa em uma cebola. Ela tem várias camadas, e o centro é sempre protegido pelas camadas externas. Na Clean Architecture funciona igual:
┌─────────────────────────────────┐ │ Frameworks & Drivers │ ← Camada mais externa (banco, web, UI) │ ┌─────────────────────────┐ │ │ │ Interface │ │ ← Controllers, Presenters, Gateways │ │ ┌─────────────────┐ │ │ │ │ │ Use Cases │ │ │ ← Regras de aplicação │ │ │ ┌───────────┐ │ │ │ │ │ │ │ Entities │ │ │ │ ← Núcleo: regras de negócio puras │ │ │ └───────────┘ │ │ │ │ │ └─────────────────┘ │ │ │ └─────────────────────────┘ │ └─────────────────────────────────┘
A regra de ouro: as dependências sempre apontam para dentro. As camadas externas conhecem as internas, mas nunca o contrário.
O que cada camada faz?
Entities — O coração do sistema
São as regras de negócio mais fundamentais da sua aplicação. Coisas que não mudam independente de qualquer tecnologia. Se você tem um sistema de petshop, a regra "um animal precisa de nome e espécie" é uma Entity. Ela não sabe que existe banco de dados, API ou framework.
Use Cases — O que o sistema faz
Aqui vivem as ações do sistema: "cadastrar animal", "agendar consulta", "gerar relatório". Os Use Cases orquestram as Entities para cumprir um objetivo. Eles sabem o que precisa acontecer, mas não sabem como os dados chegam ou onde são salvos.
Interface Adapters — A ponte
Essa camada traduz os dados do mundo externo para o formato que os Use Cases entendem, e vice-versa. Controllers, Presenters e Gateways moram aqui. É como um tradutor entre o "mundo real" e o núcleo da aplicação.
Frameworks & Drivers — O mundo externo
Banco de dados, frameworks web, bibliotecas de terceiros, interface gráfica. Tudo que é detalhe de infraestrutura fica aqui, na borda do sistema. Trocar de PostgreSQL para MongoDB? Só mexe nessa camada.
Por que isso importa na prática?
Imagine que você construiu um sistema de agendamento para o petshop da Maya, do Pancho e do Romeu. Com Clean Architecture:
- Quer trocar o banco de dados? Só muda a camada externa. As regras de negócio não sabem que o banco existia.
- Quer criar uma versão mobile do sistema? Adiciona uma nova Interface Adapter. O resto continua igual.
- Quer escrever testes? As Entities e Use Cases são puro Python — sem dependência de framework, testáveis de forma isolada e rápida.
- Entrou um dev novo no time? A estrutura de pastas conta a história do sistema, não da tecnologia usada.
O erro mais comum
Muitos devs confundem Clean Architecture com "criar muitas pastas". Não é isso.
O ponto central é a direção das dependências. Se sua Entity importa algo do seu framework ou do banco de dados, você violou a arquitetura — não importa quantas pastas você criou.
A pergunta certa não é "em qual pasta coloco esse arquivo?", mas sim "esse código depende de quê?"
Clean Architecture + SOLID = dupla imbatível
Se você leu o post sobre SOLID, vai perceber que os princípios se encaixam perfeitamente aqui:
- O SRP garante que cada camada tem uma responsabilidade única
- O OCP permite adicionar novos Use Cases sem mexer nos existentes
- O DIP é exatamente o que garante que o núcleo não depende de detalhes externos
Clean Architecture é, na prática, o SOLID aplicado em escala de projeto inteiro.