trgclub — Multi-module repo scaffold

TLDR: Criar o repo trgclub no padrão WeHive multi-module, absorvendo trgclub-api como modules/backend e trgclub-web como modules/frontend, com K8s, Terraform e CI/CD para staging e production, expostos inicialmente em endpoints beta.*.

Contexto

Os repos trgclub-api (Rails) e trgclub-web (Next.js) existem como repos independentes e precisam ser unificados em um repo multi-module seguindo o padrão estabelecido em nectar-charges. A migração será feita em dois momentos: primeiro os serviços sobem em endpoints beta.* para validação e migração de dados; depois o DNS definitivo é trocado.

Objetivos

  • Criar o repo trgclub com estrutura multi-module idêntica ao nectar-charges
  • Mover o conteúdo de trgclub-api para modules/backend
  • Mover o conteúdo de trgclub-web para modules/frontend
  • Criar K8s (base + overlays staging/production) para ambos os módulos
  • Criar Terraform (DNS, namespace, secrets) para ambos os módulos
  • Criar GitHub Actions (review-pr, check-main, deploy-staging, deploy-production)
  • Configurar endpoints beta para validação pré-migração de DNS

Fora de escopo

  • Migração de dados do banco de dados (fora do escopo deste spec)
  • Troca de DNS definitiva (será feita em etapa posterior)
  • Alterações de código dentro de trgclub-api ou trgclub-web
  • Criação de ECR repositories (existentes ou via tasks/registry/create.sh)

DNS

Staging

| Módulo | Endpoint beta | |———-|———————————-| | backend | beta.staging.api.trgclub.com | | frontend | beta.staging.trgclub.com |

Production

| Módulo | Endpoint beta | |———-|—————————-| | backend | beta.api.trgclub.com | | frontend | beta.trgclub.com |

Pós-migração (definitivos, fora deste spec)

| Módulo | Endpoint definitivo | |———-|———————–| | backend | api.trgclub.com | | frontend | trgclub.com |

Mudanças

Estrutura de arquivos a criar

trgclub/ ├── .commons -> /path/to/commons # symlink criado via make ├── .env.example ├── .gitignore ├── .tool-versions ├── .github/ │ ├── PULL_REQUEST_TEMPLATE.md │ └── workflows/ │ ├── check-main.yml │ ├── review-pr.yml │ ├── deploy-staging.yml │ └── deploy-production.yml ├── .project/ │ ├── docker/compose/services.yml │ └── docs/ │ └── specs/ ├── Makefile ├── compose.yml ├── tasks/ │ └── registry/create.sh └── modules/ ├── backend/ # conteúdo de trgclub-api │ ├── .module/make/main.mk │ ├── .infra/ │ │ ├── build-args │ │ ├── k8s/ │ │ │ ├── base/specs/ │ │ │ │ ├── api-deployment.yaml │ │ │ │ ├── api-service.yaml │ │ │ │ ├── ingress.yaml │ │ │ │ ├── migrate-job.yaml │ │ │ │ └── worker-deployment.yaml │ │ │ ├── base/kustomization.yaml │ │ │ └── overlays/ │ │ │ ├── staging/ │ │ │ └── production/ │ │ └── terraform/ │ │ ├── backend.tf │ │ ├── data.tf │ │ ├── database.tf │ │ ├── dns.tf │ │ ├── main.tf │ │ ├── namespace.tf │ │ ├── secrets.tf │ │ ├── variables.tf │ │ └── versions.tf │ └── Makefile └── frontend/ # conteúdo de trgclub-web ├── .module/make/main.mk ├── .infra/ │ ├── build-args │ ├── k8s/ │ │ ├── base/specs/ │ │ │ ├── web-deployment.yaml │ │ │ ├── web-service.yaml │ │ │ ├── ingress.yaml │ │ │ └── rbac.yaml │ │ ├── base/kustomization.yaml │ │ └── overlays/ │ │ ├── staging/ │ │ └── production/ │ └── terraform/ │ ├── backend.tf │ ├── data.tf │ ├── dns.tf │ ├── main.tf │ ├── variables.tf │ └── versions.tf └── Makefile

Parâmetros chave (derivados do padrão nectar-charges)

Parâmetro Valor
app_name trgclub
namespace staging trgclub--staging
namespace production trgclub--production
ECR backend 616795656532.dkr.ecr.us-east-1.amazonaws.com/trgclub-backend
ECR frontend 616795656532.dkr.ecr.us-east-1.amazonaws.com/trgclub-frontend
TF state backend stacks/trgclub/backend/terraform.tfstate
TF state frontend stacks/trgclub/frontend/terraform.tfstate
ward_path trgclub.infra
API_PORT A definir (seguir tabela de portas do commons)
WEB_PORT A definir (seguir tabela de portas do commons)

Terraform — main.tf backend

hcl locals { environment = terraform.workspace namespace = "trgclub--${local.environment}" domain = "trgclub.com" # staging: beta.staging.api.trgclub.com # production: beta.api.trgclub.com app_subdomain = local.environment == "production" ? "beta.api" : "beta.staging.api" app_fqdn = "${local.app_subdomain}.${local.domain}" }

Terraform — main.tf frontend

hcl locals { environment = terraform.workspace namespace = "trgclub--${local.environment}" domain = "trgclub.com" # staging: beta.staging.trgclub.com # production: beta.trgclub.com app_subdomain = local.environment == "production" ? "beta" : "beta.staging" app_fqdn = "${local.app_subdomain}.${local.domain}" }

Stack dos módulos

Módulo Stack detectada Motivo
backend Ruby/Rails trgclub-api tem Gemfile
frontend Next.js/Node trgclub-web tem package.json

build-args backend: STACK=ruby, STACK_VERSION= (ler de .ruby-version no trgclub-api) build-args frontend: STACK=node, STACK_VERSION= (ler de .tool-versions no trgclub-web)

CI/CD

Workflows idênticos ao nectar-charges com app_name: trgclub e URLs de environment corretas: - staging backend: https://beta.staging.api.trgclub.com - staging frontend: https://beta.staging.trgclub.com - production backend: https://beta.api.trgclub.com - production frontend: https://beta.trgclub.com

Como verificar

  1. make backend.run.test e make frontend.run.test passam no novo repo
  2. terraform plan em modules/backend/.infra/terraform e modules/frontend/.infra/terraform não apresenta erros
  3. kubectl kustomize modules/backend/.infra/k8s/overlays/staging e production renderizam sem erros
  4. GitHub Actions review-pr e check-main aparecem corretamente no repositório
  5. Após deploy staging: https://beta.staging.api.trgclub.com/health responde 200
  6. Após deploy staging: https://beta.staging.trgclub.com carrega o frontend

Documentação

.project/docs/modules.md descreve a divisão backend/frontend, seguindo o padrão do nectar-charges.