Diagrama de componentes

O diagrama de componentes abre um container e mostra as peças dentro dele.

É o nível que mais rende quando o container é grande e a equipe é nova nele, e o que mais envelhece quando o time refatora com frequência. Não é obrigatório descer até aqui em todo container — desça onde a pergunta existe.

Os componentes

Cada componente é uma caixa com parent apontando para o container:

elements:
  - id: servico-de-reserva
    name: Servico de Reserva
    shape: component
    parent: api
    technology: TypeScript
    description: Confere conflito de horario e confirma a reserva.

  - id: repositorio-de-reservas
    name: Repositorio de Reservas
    shape: component
    parent: api
    technology: TypeScript
    description: Le e grava reservas.

  - id: publicador
    name: Publicador
    shape: component
    parent: api
    technology: TypeScript
    description: Poe a reserva confirmada na fila de sincronizacao.

relations:
  - from: servico-de-reserva
    to: repositorio-de-reservas
    kind: sync
    label: Consulta e grava

  - from: repositorio-de-reservas
    to: banco
    kind: sync
    label: Le e grava

  - from: servico-de-reserva
    to: publicador
    kind: sync
    label: Pede a publicacao

  - from: publicador
    to: fila-de-sincronizacao
    kind: async
    label: Enfileira a reserva confirmada

O que saiu do arquivo de containers

Duas relações desapareceram de containers.yaml:

relations:
  - from: api
    to: banco
    kind: sync
    label: Le e grava

  - from: api
    to: fila-de-sincronizacao
    kind: async
    label: Enfileira a reserva confirmada

Elas foram reescritas no nível de componente, apontando para quem de fato faz o trabalho: repositorio-de-reservas → banco e publicador → fila-de-sincronizacao.

O diagrama de containers não perdeu nada: as duas setas continuam lá, projetadas na API, porque os dois componentes estão dentro dela.

Uma relação não desceu: painel → api. Isso é deliberado — o painel fala com a API como um todo, e não com um componente específico dela. Escreva a seta na granularidade que você realmente conhece.

O diagrama

kind: diagram
id: componentes
title: API de Reservas — Componentes
level: component
scope: api
order: 30
neighbors: 1
relations: auto

Mesma estrutura do nível anterior, com o escopo um degrau mais fundo: scope: api abre a API por dentro, e a ausência de include mostra os filhos diretos dela.

Quando parar

Não existe obrigação de descer. Um bom critério:

desça quando alguém novo na equipe precisaria de um mapa para achar onde mexer;
desça quando o container tem mais de um motivo para mudar, e você quer que isso fique visível;
não desça quando os componentes seriam um espelho dos diretórios do código, que já estão lá e já são navegáveis;
não desça quando você não consegue se comprometer a atualizar.

Um modelo que para no nível de container e está correto vale muito mais do que um que desce até o código e mente.

Próximo passo

O nível de código — o quarto e último.