Sistemas no nível da organização: defina uma vez, reutilize em todo lugar

Existe um padrão que aparece em toda organização a partir de um certo tamanho. A equipe A documenta sua arquitetura. Adiciona uma caixa para o Authentication Service: nome, descrição, stack tecnológica. A equipe B faz o mesmo no seu projeto. A equipe C também. Três projetos, três definições separadas do mesmo sistema, cada uma um pouco diferente. Uma diz "Auth Service", outra diz "Authentication Platform", a terceira diz "Identity Provider". O mesmo sistema. Três nomes. Três descrições que enfatizam coisas diferentes. Nenhuma ligação entre elas.

Seis meses depois, a equipe de autenticação renomeia o serviço e atualiza a stack tecnológica. A mudança chega a zero desses três diagramas. A versão da realidade de cada projeto se afasta em silêncio do sistema real e das outras versões.

Esse é o problema da consistência. Ele não vem de negligência. Vem de ferramentas de arquitetura que tratam cada projeto como uma ilha. Se a única forma de representar um sistema é criá-lo dentro de um projeto, então cada projeto que toca esse sistema ganha a sua própria cópia. Cópias divergem. É o que cópias fazem.

Construímos os sistemas no nível da organização para resolver isso.

Sistemas que pertencem à organização, não a um projeto

O Archyl agora suporta dois escopos para sistemas C4. Sistemas com escopo de projeto funcionam exatamente como antes: pertencem a um único projeto e vivem no diagrama desse projeto. Sistemas com escopo de organização pertencem à sua organização. Eles existem independentemente de qualquer projeto, e qualquer projeto pode vinculá-los.

A distinção importa porque espelha o funcionamento da arquitetura real. Alguns sistemas são internos a um projeto: um microsserviço que só existe dentro daquele bounded context, um banco de dados que atende a uma única aplicação. Esses pertencem ao projeto. Mas muitos sistemas atravessam as fronteiras dos projetos: infraestrutura compartilhada, serviços de plataforma, integrações com terceiros, capacidades centrais de negócio das quais várias equipes dependem. Esses pertencem à organização.

Quando você cria um sistema no nível da organização, está fazendo uma afirmação: este sistema é uma realidade compartilhada. Nome, descrição, tecnologia e tags são definidos uma única vez. Todo projeto que o referencia vê a mesma definição.

Como funciona

Criando sistemas da organização

Os sistemas da organização são criados em uma seção dedicada da plataforma. Você define o sistema do mesmo jeito que faria em um projeto: nome, descrição, tipo (software system, sistema externo ou pessoa), tecnologia e tags. A diferença é que ele não está preso a nenhum projeto. Vive no nível da organização, visível para todas as equipes.

Vinculando sistemas a projetos

Quando você está trabalhando no diagrama de um projeto e quer referenciar um sistema da organização, você o vincula. Um modal mostra todos os sistemas da organização disponíveis, com busca. Ative os que você precisa: eles aparecem no seu diagrama na hora.

Sistemas vinculados se comportam no diagrama como sistemas nativos. Você pode posicioná-los onde fizer mais sentido para o layout daquele projeto. Pode criar relacionamentos de e para eles. Pode descer até os containers e componentes deles. A única diferença é que a identidade central do sistema (nome, descrição, tecnologia) vem da definição da organização, não do projeto.

Cada projeto guarda a sua própria posição para o sistema vinculado, então o mesmo sistema pode ficar em lugares diferentes em diagramas diferentes. O layout é por projeto. A definição é compartilhada.

Desvinculando

Se um projeto não depende mais de um sistema compartilhado, desvincule-o. O sistema some do diagrama do projeto, mas continua existindo no nível da organização e em todos os outros projetos que o referenciam. Nenhum dado se perde. Nenhuma outra equipe é afetada.

Por que isso importa

Consistência sem coordenação

A abordagem tradicional para manter a documentação de arquitetura consistente é o processo. Você escreve convenções de nomes. Faz reuniões de revisão. Pede às pessoas que confiram como as outras equipes chamaram o mesmo sistema. O processo funciona até deixar de funcionar, o que geralmente acontece no momento em que alguém está com pressa, ou seja, quase sempre.

Os sistemas no nível da organização tornam a consistência estrutural. Existe uma única definição. Os projetos a referenciam. Quando alguém atualiza a descrição ou a stack tecnológica do sistema, todo projeto vinculado reflete a mudança automaticamente. Sem mensagens no Slack. Sem "por favor, atualize seu diagrama". A arquitetura continua consistente porque o próprio modelo de arquitetura garante isso.

Dependências entre projetos precisas

Quando vários projetos vinculam o mesmo sistema da organização, a plataforma conhece essas conexões. Não é uma convenção visual: é um relacionamento nos dados. O Impact Radar consegue rastrear dependências pelos sistemas da organização através das fronteiras dos projetos. Se você analisa o impacto de mudar um serviço de plataforma compartilhado, vê todos os projetos que dependem dele, porque todos vinculam o mesmo sistema em vez de manter cópias independentes.

Onboarding e descoberta

Pessoas novas que entram em um projeto veem os mesmos nomes de sistema, as mesmas descrições e os mesmos rótulos de tecnologia que todos os outros projetos usam. Não existe o momento "qual Auth Service é este?". O sistema da organização carrega a sua identidade consigo, e essa identidade é a mesma em todo lugar.

Menos duplicação

Além do ganho de consistência, os sistemas da organização simplesmente reduzem trabalho. Em vez de cada projeto documentar de forma independente a mesma infraestrutura (o message broker, o API gateway, o provedor de identidade, a stack de monitoramento), você define cada um uma única vez. Os projetos os vinculam em segundos. O tempo gasto recriando as mesmas caixas com rótulos um pouco diferentes cai a zero.

O que muda no modelo de dados

Por baixo dos panos, a entidade de sistema C4 agora suporta dois escopos mutuamente exclusivos. Um sistema pertence a um projeto ou a uma organização: nunca aos dois, nunca a nenhum. Isso é garantido no banco de dados por uma restrição.

Uma tabela de vínculo separada registra quais projetos referenciam quais sistemas da organização, junto com a posição por projeto no diagrama. Isso significa que o mesmo sistema pode aparecer em dez diagramas de projeto diferentes, cada um posicionado de um jeito, cada um com o seu próprio conjunto de relacionamentos com os elementos locais do projeto.

Quando você carrega o modelo C4 de um projeto, a plataforma busca tanto os sistemas próprios do projeto quanto os sistemas da organização vinculados a ele. Eles se integram de forma transparente no diagrama. A distinção é visível na interface (os sistemas da organização têm um indicador discreto mostrando que são compartilhados), mas, do ponto de vista funcional, eles participam do modelo de arquitetura da mesma forma que os sistemas do projeto.

O quadro maior

Este recurso faz parte de uma direção mais ampla: fazer o Archyl funcionar do jeito que as organizações realmente funcionam. Arquitetura não é uma coleção de projetos independentes. É uma rede de sistemas compartilhados, capacidades de plataforma e aspectos transversais. As ferramentas deveriam refletir isso.

Os sistemas no nível da organização são o primeiro passo em direção a um modelo em que a infraestrutura compartilhada é documentada uma vez e referenciada em todo lugar. Junto com a visão de Arquitetura Global para a visualização entre projetos e o Impact Radar para a análise de dependências entre projetos, você agora tem uma plataforma que entende a sua arquitetura como um todo conectado, e não como um conjunto de diagramas desconectados.

Como começar

Os sistemas no nível da organização já estão disponíveis. Vá até a seção da organização, crie seus sistemas compartilhados e depois vincule-os a qualquer projeto pela visão do diagrama. Se você já documentou o mesmo sistema em vários projetos, esta é a chance de consolidar: defina uma vez, vincule em todo lugar e aposente as cópias.

A sua arquitetura tem uma única fonte da verdade. A sua documentação também deveria ter.

Para saber mais sobre arquitetura entre projetos, veja Arquitetura Global e colaboração em tempo real. Para entender como as mudanças em sistemas compartilhados se propagam, experimente o Impact Radar. Para mudanças governadas em sistemas compartilhados, conheça as Architecture Change Requests.