Pular para conteúdo

Organização de Repositórios

Este documento define como a Arkorizon deve organizar repositórios conforme cresce em produtos, serviços, agents, bibliotecas, SDKs, CLIs, documentação e infraestrutura.

Objetivo

Garantir que cada repositório tenha responsabilidade clara, ciclo de vida próprio e nome previsível.

Estratégia padrão

A Arkorizon deve preferir multi-repo quando componentes têm deploy, ownership ou release independentes.

Monorepo pode ser usado quando vários módulos precisam evoluir juntos e possuem forte acoplamento operacional.

Quando usar multi-repo

Use repositórios separados quando houver:

  • deploy independente;
  • release independente;
  • times responsáveis diferentes;
  • stack tecnológica diferente;
  • requisitos de segurança diferentes;
  • necessidade de permissões isoladas;
  • componente reutilizável por vários produtos.

Exemplos:

arkorizon-iam-auth-service
arkorizon-iam-user-service
arkorizon-arkai-api
arkorizon-arkai-web
arkorizon-arkai-desktop-agent
arkorizon-security-lib
arkorizon-java-sdk
developer-handbook

Quando usar monorepo

Use monorepo quando:

  • módulos precisam ser versionados juntos;
  • mudanças atravessam vários pacotes com frequência;
  • o produto é pequeno ou está em estágio inicial;
  • o custo de múltiplos repositórios é maior que o benefício;
  • há forte acoplamento entre frontend/backend/infra no mesmo produto.

Exemplo:

arkorizon-arkai
|-- apps
|   |-- web
|   |-- api
|-- packages
|   |-- ui
|   |-- domain
|-- docs
|-- infra

Tipos de repositório

Tipo Exemplo Observação
Produto arkorizon-arkai Pode ser monorepo ou repositório guarda-chuva.
Backend service arkorizon-iam-auth-service Deploy independente.
Web app arkorizon-arkai-web Frontend de produto.
Agent arkorizon-arkai-desktop-agent Software instalado/local.
Worker arkorizon-arkai-indexing-worker Processo assíncrono.
Library arkorizon-security-lib Reutilizável por serviços.
SDK arkorizon-java-sdk Consumo por usuários internos/externos.
CLI arkorizon-arkai-cli Ferramenta de linha de comando.
Docs developer-handbook Documentação técnica.
Infra arkorizon-platform-infra Infraestrutura como código.
Template arkorizon-spring-service-template Base para novos projetos.

Estrutura mínima de um repositório

Todo repositório deve ter:

README.md
.github/
.gitignore

Quando aplicável:

docs/
Dockerfile
docker-compose.yml
mkdocs.yml
pom.xml
package.json
infra/
scripts/

Estrutura para serviço Java

arkorizon-iam-auth-service/
|-- .github/
|-- docs/
|-- src/
|   |-- main/
|   |   |-- java/
|   |   |-- resources/
|   |-- test/
|-- database/
|-- Dockerfile
|-- pom.xml
|-- README.md

Estrutura para documentação MkDocs

developer-handbook/
|-- .github/
|-- docs/
|   |-- index.md
|   |-- standards/
|   |-- architecture/
|   |-- workflow/
|-- mkdocs.yml
|-- requirements.txt
|-- README.md

Estrutura para biblioteca Java

arkorizon-security-lib/
|-- .github/
|-- src/
|-- pom.xml
|-- README.md
|-- CHANGELOG.md

Bibliotecas devem ter versionamento rigoroso e changelog claro.

Estrutura para agent desktop/local

arkorizon-arkai-desktop-agent/
|-- .github/
|-- src/
|-- installer/
|-- docs/
|-- scripts/
|-- README.md

Agents precisam documentar instalação, atualização, permissões, logs e diagnóstico.

Regras de ownership

Cada repositório deve ter responsáveis claros.

Use CODEOWNERS quando:

  • houver exigência de revisão por time específico;
  • o componente for crítico;
  • mudanças precisarem de aprovação de arquitetura, segurança ou plataforma.

Exemplo:

* @arkorizon/platform-team
/docs/ @arkorizon/docs-team

Regras de proteção

Repositórios de produção devem proteger main.

Regras recomendadas:

  • PR obrigatório.
  • CI obrigatório.
  • Revisão obrigatória.
  • CODEOWNERS quando aplicável.
  • Branch atualizada antes do merge.
  • Bloqueio de force-push.
  • Bloqueio de deleção.
  • Branch naming obrigatório.

Critérios para arquivar repositório

Arquive quando:

  • o componente foi substituído;
  • não há mais manutenção;
  • o código foi migrado;
  • o produto foi descontinuado.

Antes de arquivar:

  • atualize o README;
  • indique substituto;
  • garanta que releases antigas continuam rastreáveis;
  • remova secrets e permissões desnecessárias.

Regra final

Um repositório deve ter uma razão clara para existir. Se ninguém consegue explicar sua responsabilidade em uma frase, o repositório provavelmente está mal delimitado.