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¶
-
Isolamento por padrão. Cada API é um repositório independente → releases, issues e permissões isolados sem configuração adicional.
-
Centralização sem duplicação. O repositório
.githubda Organization centraliza templates, workflows reutilizáveis e políticas → evita copiar e colar CI/CD em cada repositório. -
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.
-
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. -
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.