ADR-014 — Containerização e entrega seletiva por branches

• Status: Accepted
• Data: 2026-07-22
• Decisores: Product & Engineering
• Relacionado: ADR-002, ADR-010, SPEC-ARCH-CONTAINER-001, SPEC-ARCH-ENV-001, SPEC-DELIVERY-CI-001

Contexto

O RaizFC já possui CI de qualidade, monorepo pnpm/Turborepo, web Next.js, mobile Expo e API NestJS, mas ainda não possui containerização reproduzível nem CD real. A próxima fase será integração e teste manual após a migração visual, com orçamento inicial zero. Rebuild/deploy de todos os alvos em toda mudança desperdiçaria cota e aumentaria risco.

Decisão

1. Containerizar web e API para integração; criar imagem de toolchain/build para mobile, sem tratá-lo como serviço.
2. Adotar develop, homol e master como branches permanentes e protegidas, acessíveis normalmente somente por PR.
3. Promover na ordem feature/fix → develop → homol → master; hotfix fora dessa ordem exige PR e registro explícito.
4. Executar CI por impacto no grafo do monorepo, com fallback conservador para todos os alvos.
5. Mudança em packages/contracts valida web, mobile, API e mocks; todos os consumers precisam passar antes de qualquer deploy.
6. Deploy é seletivo por alvo, mas depende de um único quality-gate global verde.
7. Hospedar o web em um projeto Vercel Hobby: master como Production, develop/homol como Preview branches com domínio e variáveis próprios.
8. Publicar a API como imagem Docker em provider desacoplado. Render Free é permitido apenas para integração/homologação e testes iniciais sem SLA, nunca declarado como hosting produtivo definitivo.
9. Manter releases automáticas de Play Store/App Store fora do escopo atual em IS-POST-13.1.
10. Preferir recursos gratuitos; esgotamento de cota bloqueia o deploy, não reduz gates nem mistura ambientes.

Matriz de impacto normativa

Origem da mudança	Web	Mobile	API
somente web	validar/publicar	não	não
somente mobile	não	validar	não
somente API	não	não	validar/publicar
UI/shared	validar/publicar conforme consumer	validar	conforme consumer declarado
contracts/config global	validar/publicar	validar	validar/publicar

“Publicar” só ocorre no merge das branches de ambiente. PRs recebem validação e, quando útil/cabível na cota, preview web efêmero.

Consequências

• Docker e Compose tornam a integração reproduzível sem substituir Vercel/EAS.
• O pipeline precisa de classificador testável, matriz dinâmica, job agregador e deploys condicionais.
• Vercel Hobby suporta o baseline por branch, mas Custom Environments não são requisito gratuito.
• Render Free possui cold start, filesystem efêmero e 750 horas compartilhadas; testes manuais devem tolerar indisponibilidade inicial e perda do estado em memória.
• GitHub Actions em repositório privado possui franquia, não gratuidade ilimitada; cancelamento, cache e jobs seletivos são requisitos de custo.
• Proteção de branches pode exigir configuração manual e, conforme visibilidade/plano do GitHub, upgrade ou disciplina operacional do owner.

Alternativas rejeitadas

• Deploy total em todo commit: desperdiça cota e não aproveita o grafo do monorepo.
• Vercel Custom Environments como requisito: recurso pago no baseline atual.
• API NestJS na Vercel sem análise própria: conflita com scheduler/estado em memória e arquitetura de serviço atual.
• Mobile na Vercel: não corresponde ao runtime nem ao processo de distribuição das stores.
• Push direto nas branches de ambiente: remove revisão, rastreabilidade e gate de promoção.

Condições de revisão

Revisar esta decisão quando houver usuários reais, persistência de produção, necessidade de SLA, franquias gratuitas insuficientes, release mobile aprovado ou mudança de provider. A troca de provider deve preservar imagens SHA, isolamento e quality gate.