Folder architecture
The problem
A home equity operation goes through many hands (partner, analysis, legal, payment) and every stage requires documents and checks. Without a single place, operations stalled and nobody knew which stage they were in or what was missing to move on.
Every folder has one job and the rule is about what a class is, not what is convenient. This is what protects the code from rotting the most.
Decisions and why
- A controller does four things
- Reads the request, calls one use case, logs and responds. A business rule in a controller is a rule nobody finds.
- One use case, one execute()
- Every product action is a class. The class name is the documentation and the test is obvious.
- No service/ folder
- service/ becomes a dumping ground. Product actions are use_case/, outbound edges are client/, queries are repository/.
- OpenAPI outside the controller
- documentation/ holds the annotations; the controller stays readable.
- No try/catch
- Custom exceptions and one RestExceptionHandler shape every error response the same way.
What it looks like
Replica of the pipeline board with fictional data (internal system) esteira.evilrabbit.com.br/lines/triage
Triagem
Conferência de dados2
Marina SouzaGMR$ 480 mil 1 d
Paulo HenriqueR$ 1,2 mi hoje
Combate à fraude1
Ricardo AlvesAPR$ 750 mil 4 d
Validação dos documentos2
Carla PradoGMR$ 610 mil 2 6 d
João ReisR$ 295 mil 2 d
Aguardando aprovação0
Nada aqui