Clean Architecture

Organiza o código em camadas concêntricas em que as dependências apontam só para dentro: a regra de negócio (entidades e casos de uso) não conhece banco, HTTP nem framework. O caso de uso declara as portas de que precisa; os adaptadores da borda as implementam; um único ponto de composição liga tudo. A regra fica testável sem infraestrutura e o framework vira detalhe trocável.

passos: 6
arquivos: 9
testes: 3
tecnologias: 5

Infraestrutura realTypeScriptBunElysiaPostgreSQLDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Transferência entre contas de um banco digital com duas regras: não passar do saldo e não passar do limite diário, que recomeça a cada dia. As regras moram na entidade Account; o caso de uso orquestra débito, crédito e registro; o PostgreSQL e o HTTP ficam na borda, trocáveis sem tocar no núcleo.

Planta

Fluxo

8/8

8 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num nó para focar
Outras plantas de fluxo

Como funciona

6 passos

Dependências apontam para o domínio.

Esconde cada passo: lembre antes de tocar para revelar.

01
Account guarda as invariantes em centavos: saldo checado antes do limite; limite de outro dia não conta
02
UseCaseTransfer declara as portas que usa; recebe e devolve DTOs simples, nunca linha de banco nem Request
03
A porta de unidade de trabalho promete tudo-ou-nada; o adaptador cumpre com uma transação que trava as contas em ordem de id
04
O controller traduz request em DTO e erro de domínio em status HTTP, sem regra de negócio
05
app_clean.ts é o único lugar que conhece as implementações concretas
06
Testes em pirâmideEntidade pura, caso de uso com fake das portas, adaptador com PostgreSQL real

Trade-offs

O que se ganha, o que se paga

3 vantagenscada ganho tem um preço3 custos

Vantagens

Regra testável sem banco nem HTTP
Framework e banco trocáveis na borda
Dependências explícitas pelas portas

Custos

Mais arquivos e indireção por caso de uso
Exagero para CRUD sem regra
Disciplina para não vazar tipos da borda

apps/architecture/clean

9 arquivos

src/domain/

account.tsEntidade e erros de domínio
account.test.tstesteLimites de saldo e limite diário, virada de dia

src/application/

use_case_transfer.tsCaso de uso e portas
use_case_transfer.test.tstesteOrquestração com fake das portas

src/adapters/

repository_postgres.tsUnidade de trabalho e repositórios sobre PostgreSQL
controller_transfer.tsRota HTTP e tradução de erros
repository_postgres.test.tstesteTransação, tradução de erro e concorrência contra PostgreSQL real

src/main/app_clean.ts / src/main/