Naming Conventions

Este documento define o padrão oficial de nomenclatura da Arkorizon para repositórios, produtos, serviços, aplicações, agentes, bibliotecas, SDKs, CLIs, pacotes Java, artefatos, imagens Docker e nomes de aplicações.

O objetivo é permitir que a organização cresça com múltiplos produtos e diferentes tipos de software sem perder clareza, rastreabilidade e consistência.

Regra geral

Nomes técnicos devem ser curtos, em inglês, minúsculos quando aplicável, sem acentos e com separação por hífen para artefatos/repositórios ou ponto para pacotes Java.

Princípios

• Um nome deve deixar claro o que o componente é.
• Um nome deve deixar claro a qual produto ou domínio pertence.
• Um nome deve evitar abreviações obscuras.
• Um nome deve ser estável ao longo do tempo.
• Um nome técnico deve ser escrito em inglês.
• O mesmo conceito deve ter nomes compatíveis entre repositório, artefato, pacote, Docker image e aplicação.

Vocabulário corporativo

Termo	Significado	Exemplos
Organização	Empresa ou namespace principal.	arkorizon
Produto	Solução de negócio completa.	arkai, iam, developer-handbook
Domínio	Área funcional ou bounded context.	auth, identity, billing, knowledge
Componente	Unidade técnica dentro de um produto ou domínio.	service, web, agent, lib, sdk
Artefato	Unidade versionada e publicada.	Maven artifact, Docker image, pacote npm
Aplicação	Software executável.	API, web app, desktop agent, CLI
Biblioteca	Código reutilizável por outros projetos.	security-lib, common-lib

Tipos oficiais de componente

Tipo	Quando usar	Exemplo
service	Backend/API executável com responsabilidade de negócio.	arkorizon-iam-auth-service
web	Aplicação web frontend.	arkorizon-arkai-web
admin	Console administrativo.	arkorizon-iam-admin
agent	Aplicação local, worker ou software instalado no ambiente do usuário.	arkorizon-arkai-desktop-agent
worker	Processo assíncrono de backend.	arkorizon-arkai-indexing-worker
gateway	Entrada centralizada para APIs.	arkorizon-api-gateway
cli	Command-line interface.	arkorizon-arkai-cli
lib	Biblioteca genérica interna.	arkorizon-security-lib
sdk	SDK para consumo externo ou entre times.	arkorizon-java-sdk
docs	Documentação técnica ou de produto.	arkorizon-developer-handbook-docs
template	Template reutilizável de projeto.	arkorizon-spring-service-template
infra	Infraestrutura como código.	arkorizon-platform-infra

Padrão de repositórios

Use o formato:

arkorizon-<produto-ou-domínio>-<componente>

Para produtos fortes e reconhecíveis, o produto deve aparecer logo após arkorizon.

arkorizon-arkai-web
arkorizon-arkai-api
arkorizon-arkai-desktop-agent
arkorizon-arkai-cli
arkorizon-arkai-docs

Para domínios corporativos transversais:

arkorizon-iam-auth-service
arkorizon-iam-admin
arkorizon-iam-user-service
arkorizon-notification-service
arkorizon-billing-service

Para bibliotecas e SDKs:

arkorizon-common-lib
arkorizon-security-lib
arkorizon-observability-lib
arkorizon-java-sdk
arkorizon-python-sdk

Para documentação:

arkorizon-ai-platform-docs
arkorizon-developer-handbook
arkorizon-architecture-docs

Quando criar um novo repositório

Crie um repositório novo quando o componente tiver pelo menos uma destas características:

• ciclo de release independente;
• deploy independente;
• ownership diferente;
• stack tecnológica diferente;
• requisitos de segurança próprios;
• necessidade de permissões isoladas;
• uso como biblioteca/SDK por múltiplos projetos.

Evite criar repositório novo quando:

• o código não tem ciclo de vida próprio;
• o componente só existe dentro de outro produto;
• a separação aumenta complexidade sem ganho real;
• a feature ainda está em discovery e muda todos os dias.

Padrão Java groupId

Use o formato:

com.arkorizon.<produto-ou-plataforma>.<domínio-ou-componente>

Exemplos:

Caso	groupId
Serviço de autenticação do IAM	com.arkorizon.iam.auth
Serviço de usuários do IAM	com.arkorizon.iam.user
API principal da ARKAI	com.arkorizon.arkai.api
Agente desktop da ARKAI	com.arkorizon.arkai.agent.desktop
Worker de indexação da ARKAI	com.arkorizon.arkai.worker.indexing
Biblioteca de segurança	com.arkorizon.lib.security
Biblioteca comum	com.arkorizon.lib.common
SDK Java	com.arkorizon.sdk.java
Template Spring	com.arkorizon.template.spring

Padrão Maven artifactId

Use o formato:

arkorizon-<produto-ou-domínio>-<componente>

Exemplos:

<groupId>com.arkorizon.iam.auth</groupId>
<artifactId>arkorizon-iam-auth-service</artifactId>

<groupId>com.arkorizon.arkai.agent.desktop</groupId>
<artifactId>arkorizon-arkai-desktop-agent</artifactId>

<groupId>com.arkorizon.lib.security</groupId>
<artifactId>arkorizon-security-lib</artifactId>

<groupId>com.arkorizon.sdk.java</groupId>
<artifactId>arkorizon-java-sdk</artifactId>

Padrão de package Java

O package raiz deve seguir o groupId.

package com.arkorizon.iam.auth;
package com.arkorizon.iam.auth.domain;
package com.arkorizon.iam.auth.adapter.in.web;
package com.arkorizon.iam.auth.adapter.out.persistence;

Para bibliotecas:

package com.arkorizon.lib.security;
package com.arkorizon.lib.security.jwt;
package com.arkorizon.lib.security.crypto;

Para agents:

package com.arkorizon.arkai.agent.desktop;
package com.arkorizon.arkai.agent.desktop.runtime;
package com.arkorizon.arkai.agent.desktop.integration;

Nome da aplicação Spring Boot

Use o mesmo nome do repositório ou artifact executável.

spring:
  application:
    name: arkorizon-iam-auth-service

Exemplos:

Componente	spring.application.name
IAM Auth Service	arkorizon-iam-auth-service
ARKAI API	arkorizon-arkai-api
Notification Service	arkorizon-notification-service
Indexing Worker	arkorizon-arkai-indexing-worker

Docker images

Use o formato:

<registry>/arkorizon/<nome-do-repositório>:<tag>

Exemplos:

ghcr.io/arkorizon/arkorizon-iam-auth-service:1.0.0
ghcr.io/arkorizon/arkorizon-arkai-api:1.4.2
ghcr.io/arkorizon/arkorizon-arkai-desktop-agent:0.9.0-beta.1
ghcr.io/arkorizon/arkorizon-notification-service:2.1.0

Tags permitidas:

Tag	Uso
1.2.3	Release estável.
1.2.3-rc.1	Release candidate.
1.2.3-beta.1	Beta.
sha-<commit>	Build rastreável por commit.
main	Último build da branch principal, quando necessário.
latest	Permitido apenas para imagens públicas ou ambientes simples; não usar como referência de produção crítica.

Labels OCI para imagens Docker

Toda imagem publicada deve incluir labels OCI quando possível.

LABEL org.opencontainers.image.title="arkorizon-iam-auth-service"
LABEL org.opencontainers.image.description="Arkorizon IAM authentication service"
LABEL org.opencontainers.image.source="https://github.com/Arkorizon/arkorizon-iam-auth-service"
LABEL org.opencontainers.image.version="1.0.0"
LABEL org.opencontainers.image.revision="${GIT_COMMIT}"

Exemplos por tipo de software

Tipo	Repositório	groupId	artifactId
API backend	arkorizon-iam-auth-service	com.arkorizon.iam.auth	arkorizon-iam-auth-service
Produto ARKAI	arkorizon-arkai-api	com.arkorizon.arkai.api	arkorizon-arkai-api
Agent instalado no PC	arkorizon-arkai-desktop-agent	com.arkorizon.arkai.agent.desktop	arkorizon-arkai-desktop-agent
Lib genérica	arkorizon-common-lib	com.arkorizon.lib.common	arkorizon-common-lib
SDK Java	arkorizon-java-sdk	com.arkorizon.sdk.java	arkorizon-java-sdk
CLI	arkorizon-arkai-cli	com.arkorizon.arkai.cli	arkorizon-arkai-cli
Documentação	developer-handbook	Não aplicável	Não aplicável

Regras finais

• Use inglês para nomes técnicos.
• Use kebab-case para repositórios, artefatos e Docker images.
• Use lower case com pontos para packages Java.
• Use arkorizon- como prefixo de repositórios e artefatos públicos/internos.
• Não use nomes genéricos como backend, server, api2, new-service ou utils.
• Não use siglas internas sem documentação.
• Prefira nomes que expressem responsabilidade de negócio.
• Não inclua ambiente no nome do repositório. Ambiente pertence a configuração/deploy, não ao nome do software.