Mapa de propriedade

O Mapa de propriedade oferece uma visão geral de quem é responsável por cada parte da sua arquitetura. Equipes e usuários aparecem como bolhas interativas, dimensionadas pela quantidade de elementos que possuem. Passe o mouse para revelar as linhas de dependência entre proprietários e clique para explorar os elementos pelos quais cada equipe ou pessoa é responsável.

Conceitos principais

Proprietários

Cada elemento C4 (system, container, component) pode ser atribuído a um ou mais proprietários:

Um elemento pode ter proprietários de equipe e proprietários de usuário ao mesmo tempo. Elementos sem nenhum proprietário são rastreados como sem dono e contribuem para lacunas de cobertura.

Cobertura

A cobertura mede quantos elementos da sua arquitetura possuem pelo menos um proprietário atribuído. O cabeçalho do mapa de propriedade exibe:

• Porcentagem de cobertura geral -- verde (80%+), amarelo (50-79%) ou vermelho (abaixo de 50%)
• Detalhamento por nível -- estatísticas separadas para systems, containers e components
• Quantidade atribuídos / total -- números brutos para referência rápida

Dependências

Quando existem relacionamentos C4 entre elementos pertencentes a equipes diferentes, o mapa de propriedade desenha linhas de dependência entre esses proprietários. Isso evidencia o acoplamento entre equipes -- por exemplo, "os serviços da equipe de Frontend dependem do API Gateway da equipe de Plataforma."

As dependências são:

• Agregadas a partir de relacionamentos C4 individuais em arestas de proprietário para proprietário
• Ponderadas pela quantidade de relacionamentos subjacentes (mais espessa = mais dependências)
• Exibidas ao passar o mouse para manter a visão geral limpa

Usando o Mapa de propriedade

Visão geral

Navegue para Arquitetura Global -> Propriedade. A visão geral mostra todas as equipes e usuários como bolhas coloridas:

• Tamanho da bolha reflete quantos elementos o proprietário é responsável
• Cor da bolha é atribuída automaticamente por equipe/usuário
• Ícone da equipe/usuário ou avatar é exibido dentro de cada bolha, quando disponível

As bolhas são posicionadas usando um layout de força direcionada que agrupa naturalmente proprietários conectados mais próximos uns dos outros.

Passar o mouse

Passe o mouse sobre qualquer bolha para:

1. Ver um tooltip com o nome completo do proprietário e a quantidade de elementos
2. Revelar linhas de dependência fluindo para proprietários conectados (com tracejados animados e badges de contagem)
3. Esmaecer bolhas não relacionadas para que a vizinhança de propriedade se destaque

Ampliando

Clique em qualquer bolha para ampliar e ver uma visualização detalhada dos elementos desse proprietário:

1. Uma animação de revelação circular faz a transição da bolha para um painel de detalhes em tela cheia
2. O cabeçalho principal mostra o ícone, nome, tipo (Equipe/Usuário) e cards de estatísticas do proprietário
3. Os cards de estatísticas funcionam como filtros -- clique em "Systems", "Containers" ou "Components" para exibir apenas esse tipo
4. Os elementos são exibidos em um grid de cards agrupados por nível C4, contendo:
   • Nome e descrição do elemento
   • Nome do projeto
   • Pills de co-propriedade (outras equipes/usuários que também possuem este elemento)
5. Pressione Escape ou clique em Voltar para retornar à visão geral

Pesquisa

A barra de pesquisa filtra no nível das bolhas. Digite qualquer combinação de:

• Nome do proprietário -- ex.: "Plataforma" ou "Alice"
• Nome do elemento -- ex.: "API Gateway"
• Nome do projeto -- ex.: "Payment Service"

A pesquisa utiliza correspondência de texto completo: todos os termos devem aparecer em algum lugar no nome do proprietário, nos nomes dos elementos ou nos nomes dos projetos da bolha.

Elementos sem dono

Clique no botão sem dono no cabeçalho para revelar uma bolha cinza especial contendo todos os elementos sem nenhum proprietário. Isso ajuda a identificar lacunas de cobertura que precisam de atenção.

Atribuindo propriedade

Pelo diagrama

1. Clique com o botão direito em qualquer system, container ou component no diagrama C4
2. Abra a seção Proprietários no painel de detalhes
3. Clique em Adicionar proprietário e selecione uma equipe ou usuário
4. O mapa de propriedade é atualizado automaticamente

Pela visualização detalhada do Mapa de propriedade

Ao ampliar uma equipe ou usuário, os elementos listados mostram sua propriedade atual. Navegue até o elemento no diagrama do projeto para modificar os proprietários.

Pela API

Use os endpoints de proprietários de elementos para atribuir propriedade programaticamente:

Definir proprietários de equipe:

PUT /api/v1/c4/systems/:id/owners
Content-Type: application/json
Authorization: Bearer <token>

{
  "teamOwnerIds": ["<team-uuid-1>", "<team-uuid-2>"],
  "userOwnerIds": ["<user-uuid-1>"]
}

O mesmo padrão de endpoint funciona para containers (/c4/containers/:id/owners) e components (/c4/components/:id/owners).

Boas práticas

Atribua propriedade cedo

• Defina a propriedade da equipe ao criar ou descobrir novos systems
• Inclua a propriedade no seu processo de revisão do AI discovery
• Busque 80%+ de cobertura em todos os níveis C4

Prefira equipes a usuários individuais

• Equipes sobrevivem à rotatividade de colaboradores -- propriedade individual cria silos de conhecimento
• Atribua equipes como proprietários principais e adicione usuários individuais para responsabilidade quando necessário
• Mapeie equipes para a estrutura real de squads ou domínios da sua organização

Revise dependências entre equipes

• Passe o mouse sobre cada equipe periodicamente para verificar as linhas de dependência
• Contagens altas de dependência entre duas equipes podem indicar acoplamento forte
• Use essa informação para embasar decisões sobre limites de serviço e trabalho em API contracts

Acompanhe a cobertura ao longo do tempo

• Monitore a porcentagem de cobertura no cabeçalho
• Trate elementos sem dono antes que se acumulem
• Considere 100% de cobertura de propriedade como uma meta de higiene, não uma tarefa pontual

Próximos passos

• Architecture Decision Records -- Documente decisões vinculadas a elementos com proprietário
• Architecture Insights -- Detecte problemas em elementos da sua equipe
• Release Management -- Acompanhe deploys para systems com proprietário
• API Contracts -- Documente APIs entre fronteiras de equipes