Módulo de back-end no padrão das skills wehive

TLDR: remover do modules/backend os metadados de repo que vazaram para dentro do módulo, completar o conjunto padrão de entrypoints com lint, e mover o app/ para o layout completo da Arrow Architecture — antes que qualquer código de domínio chegue.

Nota de status: a spec original ficou marcada como proposed. Está implementada — o app/ tem core/ports/bridges/platform e os metadados de repo não estão versionados dentro do módulo. Duas coisas mudaram depois da spec: a camada de terceiros chama-se bridges/, não external/, e os entrypoints vivem em run/, não em bin/.

Contexto

O scaffold Rails da spec 20260723085311 deixou modules/backend divergindo das skills wehive em três pontos:

Skill Divergência
commons:structure / modules.md O módulo contém .claude/, .codex/ (symlinks) e .project/ai/ — metadados de nível de repo que nunca pertencem a um módulo. Estão até cobertos pelo .gitignore (modules/**/.claude/), mas foram commitados assim mesmo. Um módulo guarda só .module/, seu Makefile e suas fontes
commons:structure (entrypoints) O conjunto padrão é runtime, install, test, lint. O back tem os três primeiros e não tem lint (o front tem). Cada entrypoint <name> vira make backend.<name> automaticamente, via make/core/commands.mk do commons
commons:rails (Arrow Architecture) O app/ usa o layout default do Rails (controllers/, jobs/, models/) em vez de core/ports/terceiros/platform. O módulo ainda não tem código de domínio — só a fundação da USER-001 —, então a mudança é barata agora e evita um refactor disruptivo depois

Decisões já tomadas com o owner: escopo completo (layout + Arrow), manter todos os binstubs do Rails (dev, setup, ci, thrust, etc.), criar a task no Asana.

Asana: https://app.asana.com/1/1208104128529800/project/1214395788660507/task/1216836595697181

Objetivos

  • modules/backend livre de metadados de nível de repo (.claude/, .codex/, .project/).
  • Conjunto padrão de entrypoints completo: runtime, install, test, lint.
  • app/ no layout da Arrow Architecture, com autoloading configurado e zeitwerk:check passando.
  • Árvore de testes espelhando o novo layout de app/.
  • Suíte verde (make backend.test) e healthcheck funcionando depois da mudança.

Fora de escopo

  • Adicionar good_job, tabela Event ou qualquer maquinário assíncrono.
  • Deploy do back-end / conteúdo de .infra/backend/.
  • Remover os binstubs do Rails deixados pelo rails new (o owner escolheu mantê-los).
  • Qualquer mudança em modules/frontend.

Mudanças

Estrutura do módulo

Remover (git rm) modules/backend/.claude/ (symlinks commands, skills), modules/backend/.codex/ (idem) e modules/backend/.project/ai/ (só .gitkeeps). O .gitignore já ignora esses caminhos para módulos, então eles ficam de fora dali em diante.

Criar o entrypoint lint (executável):

```bash #!/usr/bin/env bash set -e

exec bundle exec rubocop “$@” ```

Arrow Architecture

Moves de arquivo (git mv, sem mudança de conteúdo além do que o autoloading exige):

De Para
app/controllers/application_controller.rb app/ports/controllers/application_controller.rb
app/controllers/health_controller.rb app/ports/controllers/health_controller.rb
app/controllers/api/v1/base_controller.rb app/ports/controllers/api/v1/base_controller.rb
app/controllers/concerns/paginatable.rb app/ports/controllers/concerns/paginatable.rb
app/jobs/application_job.rb app/ports/jobs/application_job.rb
app/models/application_record.rb app/core/application_record.rb
  • Remover as pastas agora vazias app/controllers/, app/jobs/, app/models/ (incluindo os concerns/.keep).
  • Criar as demais pastas principais da Arrow, seguradas por .keep onde vazias — a camada de terceiros e app/platform/. O layout completo fica visível na árvore desde o primeiro dia.

  • config/application.rb — registrar os diretórios de ports como autoload roots:

    ruby %w[controllers controllers/concerns jobs].each do |dir| path = root.join("app/ports/#{dir}") config.autoload_paths << path config.eager_load_paths << path end

No código atual, a camada de terceiros é app/bridges/, app/core/ está subdividido em models/ e use_cases/ (ambos autoload roots), e serializers entrou na lista de ports. Ver Camadas do app Rails.

Testes

  • test/controllers/** → test/ports/controllers/**, espelhando o app/ (as referências de classe não mudam; o Minitest faz glob em test/**/*_test.rb).
  • test/integration/ e test/models/ ficam como estão (test/models/ guarda só um .keep até a primeira entidade).

Como verificar

  • make backend.test — suíte verde
  • make backend.lint — roda rubocop pelo novo entrypoint
  • cd modules/backend && bin/rails zeitwerk:check — autoloading consistente com o novo layout
  • make backend.up e curl localhost:4010/health → 200
  • ls modules/backend/app → core, ports, platform e a camada de terceiros
  • git ls-files modules/backend | grep -E '\.claude|\.codex|modules/backend/\.project' → vazio

Documentação