Neste artigo
- Como organizar um projeto Node.js do zero sem virar bagunça
- A estrutura por camadas que escala com o projeto
- As 3 regras que impedem a bagunça de voltar
- Do zero ao primeiro commit organizado
- Por que a estrutura importa na entrevista
- Preciso dessa estrutura desde o primeiro dia?
- Onde entram os testes nesse desenho?
- Vale usar um gerador de estrutura pronta?
- Como organizar um projeto que já está bagunçado?
Como organizar um projeto Node.js do zero sem virar bagunça
Todo projeto Node.js nasce organizado no primeiro dia, e a bagunça chega na 3ª semana, quando a pasta de utilidades virou lixeira e ninguém sabe mais onde o bug mora. A diferença entre projeto que escala e projeto que vira dor é a estrutura definida antes do primeiro arquivo solto.
Organizar um projeto Node.js do zero leva menos de 1 hora com o mapa certo, e este guia entrega a estrutura por camadas, o papel de cada pasta e as 3 regras que impedem a bagunça de voltar. O objetivo é simples: que qualquer pessoa do time encontre o código sem te ligar.
A estrutura por camadas que escala com o projeto
A organização que funciona para projetos de estudo e para os primeiros anos de produto separa o código pelo papel que ele cumpre, e não pelo tipo de arquivo. Cada pasta tem dono conceitual, e a regra de importação segue um sentido só.
O sentido das importações é o que impede a queda de domino: routes chama controllers, controllers chama services, services chama repositories, e o caminho inverso é proibido. Com esse contrato, a troca de banco de dados não toca a regra de negócio, e a mudança de framework web não toca o banco.
As 3 regras que impedem a bagunça de voltar
- Regra 1, nada solto na raiz: além do package.json e dos arquivos de configuração, a raiz fica vazia. Script de manutenção criado às pressas na raiz hoje é o arquivo órfão de amanhã.
- Regra 2, o util é a última porta: pasta de helpers só recebe função usada em 2 ou mais lugares, com nome que explica o que faz. Função usada em 1 lugar mora onde ela é usada.
- Regra 3, o pull request guarda o padrão: código novo que quebra as camadas volta no review com o motivo anotado. Padrão sem fiscalização é sugestão, e sugestão ninguém segue em semana de prazo.
O pull request é o fórum que o time já tem, e o critério do clean code no mundo real vale aqui: PR pequeno, com a mudança legível de ponta a ponta. Estrutura que não passa pelo review vira exceção, e exceção multiplicada é bagunça.
Do zero ao primeiro commit organizado
A sequência de criação economiza retrabalho: inicie o projeto com o manifest, crie a árvore de pastas vazia com os arquivos de índice, configure as variáveis de ambiente com o arquivo de exemplo versionado e só então escreva o primeiro endpoint, já no lugar certo.
Criar a pasta depois do código é o caminho da bagunça: código funcionando nunca quer mudar de endereço, e 2 semanas depois a exceção virou padrão.
O arquivo de variáveis de ambiente nunca vai versionado, e o arquivo de exemplo com os nomes das chaves vai: é ele que permite a outra pessoa subir o projeto sem te chamar.
O passo a passo de subir o projeto no GitHub cobre a publicação, e o README com o comando de subir e 10 linhas de contexto completa o kit que o colega monta em 15 minutos, entre clone, instalação e configuração do arquivo de ambiente.
Por que a estrutura importa na entrevista
A pergunta sobre como o candidato estrutura um projeto aparece em entrevista de backend porque revela quem já manteve código de outra pessoa. A resposta com camadas, sentido de importação e o papel do review mostra prática, e o projeto de estudo com essa estrutura é o portfólio que a conversa pede.
A trilha completa de backend está no roadmap de backend 2026 para a primeira vaga, e as vagas abertas no casado.dev mostram o que as descrições pedem desse repertório.
Perguntas frequentes
Preciso dessa estrutura desde o primeiro dia?
A árvore de pastas sim, porque criar depois custa mais, mas as camadas podem nascer vazias e ser preenchidas conforme o projeto cresce. O que não dá para atrasar é o sentido de importação, porque ele define o desenho do projeto, e reverter um fluxo já escrito em camada errada é o retrabalho caro.
Onde entram os testes nesse desenho?
Na pasta tests, espelhando a estrutura do src: o teste do service de cobrança mora em tests/services, com o mesmo nome do arquivo testado. Esse espelhamento é o que permite encontrar o teste sem procurar, e a suíte cresce organizada por padrão.
Vale usar um gerador de estrutura pronta?
Vale como partida, com leitura: os geradores populares entregam a árvore comum, e o time precisa entender cada pasta antes de codar nelas. Estrutura copiada sem entendimento produz a mesma bagunça com nomes bonitos, e a entrevista técnica cobra exatamente esse entendimento.
Como organizar um projeto que já está bagunçado?
Com migração incremental, e não com grande reescrita: a cada tarefa nova, o código tocado entra no lugar certo, e os imports antigos são atualizados no mesmo PR. Em 3 ou 4 ciclos, as partes mais movimentadas do projeto já moram no lugar certo, sem parar a entrega para reorganizar tudo de uma vez.