Ir para o conteúdo

Decisão Arquitetural

Monorepo, Multirepo ou Hybrid — análise comparativa e justificativa da decisão de repositórios para a GitHub Organization.


Análise Comparativa

Critério Monorepo Multirepo Hybrid ✓
Complexidade inicial Baixa Alta Média
Isolamento de APIs ❌ Ruim ✅ Excelente ✅ Excelente
Permissões granulares ❌ Difícil ✅ Nativo ✅ Nativo
Reutilização de templates Manual Manual Via .github
Releases independentes ❌ Complexo ✅ Nativo ✅ Nativo
Versionamento por serviço ❌ Complexo ✅ Nativo ✅ Nativo
Open source seletivo ❌ Difícil ✅ Nativo ✅ Nativo
Discovery por cliente Requer docs Requer docs Requer docs
Overhead de governança Baixo Alto Médio
Crescimento sem refatoração ❌ Problemático ✅ Natural ✅ Natural

Decisão Adotada

RECOMMENDATION — Arquitetura Hybrid com estrutura Multirepo

Arquitetura Hybrid com estrutura Multirepo orientada por tipo de repositório.

Esta é uma decisão arquitetural (RECOMMENDATION), não uma exigência normativa.


Justificativa

  1. Isolamento por padrão. Cada API é um repositório independente → releases, issues e permissões isolados sem configuração adicional.

  2. Centralização sem duplicação. O repositório .github da Organization centraliza templates, workflows reutilizáveis e políticas → evita copiar e colar CI/CD em cada repositório.

  3. Separação de audiências. Repositórios de documentação, governança e dados ficam separados do código → permissões diferentes, públicos diferentes, cadências de atualização diferentes.

  4. Transição suave para comercial. A mudança de open source para produto comercial é feita alterando a visibilidade do repositório (public → private) sem refatoração estrutural.

  5. MVP mínimo. O Stage 0 começa com apenas 4 repositórios. O overhead inicial é real, mas pequeno.

Contraponto aceito: Criar múltiplos repositórios tem custo de setup. Esse custo é mitigado pela criação faseada e pelo uso de gh repo create --template a partir do Stage 1.


Convenção de Prefixos de Repositório

{org}/                     ← GitHub Organization (ex: acme-br-apis)
│
├── .github/               ← controles da Organization
├── docs-*/                ← documentação
├── gov-*/                 ← governança (alternativa: docs-governance)
├── api-*/                 ← APIs (open source ou comerciais)
├── sdk-*/                 ← SDKs e bibliotecas cliente
├── data-*/                ← pipelines e datasets
├── svc-*/                 ← serviços de infraestrutura interna
└── infra-*/               ← infraestrutura, IaC, deploy

Open Source vs Comercial — Separação

open source code (MIT/Apache) ──────────────────► github.com/org/api-nome
open API spec (openapi.yaml) ────────────────────► github.com/org/api-nome-spec
                                                    (criado quando código vira private)
hosted service ──────────────────────────────────► api.empresa.com (privado)
premium data / enrichments ─────────────────────► acesso via plano pago
enterprise SLA / support ────────────────────────► contrato privado

LEGAL REVIEW REQUIRED

A escolha de licença open source deve ser feita com cuidado quando há intenção de criar produto comercial baseado no mesmo código.

  • AGPL pode complicar modelos SaaS.
  • Apache 2.0 ou MIT são mais permissivas para uso comercial downstream.
  • Dual licensing é uma opção para casos específicos.

Consultar advogado antes de publicar a licença definitiva.


Próximo passo

Com a decisão arquitetural estabelecida, consulte a Estrutura da GitHub Organization para ver os repositórios concretos e quando criar cada um.