Projetos

Um projeto é uma pasta diretamente sob model/. Ele faz uma coisa só: ser o dono dos identificadores dentro dele.

O mesmo api pode existir em reservas/ e em portaria/ sem colidir. É por isso que dividir um modelo grande não obriga a renomear nada.

A estrutura

• Directorymodel/

  • workspace.yaml
  • Directoryshared/ caixas que todos usam

    • project.yaml
    • elements.yaml
  • Directoryreservas/

    • project.yaml
    • elements.yaml
    • contexto.yaml
  • Directoryportaria/

    • project.yaml
    • elements.yaml
    • contexto.yaml

Declarar um projeto

Um project.yaml não é obrigatório: uma pasta com documentos dentro já é um projeto, com o nome da própria pasta. O arquivo existe para dar a ele um nome legível, uma ordem e etiquetas.

model/reservas/project.yaml

kind: project
id: reservas
name: Reservas de Salas
order: 10

Campo	O que faz
id	deve bater com o nome da pasta. Se discordar, a pasta vence e você recebe um aviso
name	o nome exibido na barra lateral
order	a posição entre os projetos. Padrão: 500
tags, meta	etiquetas e metadados do projeto

Atravessar a fronteira

Uma referência sem barra procura no projeto que a declara e depois em shared. Para alcançar outro projeto, qualifique com barra:

model/portaria/elements.yaml

elements:
  - id: portaria
    name: Controle de Portaria
    shape: system
    description: Libera a catraca de quem tem reuniao marcada no predio.

relations:
  # Uma seta que atravessa projetos: os dois lados sao ids qualificados.
  - from: portaria
    to: reservas/reservas
    kind: sync
    label: Confere a reserva do dia

Uma seta pode atravessar projetos livremente. O que decide em qual arquivo escrevê-la é organização, não permissão: quando nenhum dos dois lados deveria ser o dono da integração, um arquivo de relações próprio resolve.

O projeto shared

shared é o único nome de projeto com significado especial: ele é o segundo lugar consultado quando uma referência não tem barra.

model/shared/elements.yaml

elements:
  - id: colaborador
    name: Colaborador
    shape: actor
    description: Quem trabalha na empresa.

  - id: agenda-corporativa
    name: Agenda Corporativa
    shape: external
    technology: Google Workspace

Com isso, qualquer projeto escreve colaborador e alcança essa caixa, sem qualificar.

O que costuma morar ali: as pessoas e os papéis, os sistemas de terceiros, e as plataformas internas que todo mundo consome.

O que não deve morar em `shared`

Uma caixa que só um projeto usa. Pôr tudo em shared desfaz a única coisa que os projetos fazem — separar espaços de identificadores — e transforma a pasta num depósito.

Quando criar o segundo projeto

Crie um projeto novo quando:

• o modelo tem dois ou mais sistemas com vidas próprias, cada um com o seu conjunto de containers;
• equipes diferentes editam partes diferentes, e você quer que os arquivos delas não se cruzem;
• os identificadores começaram a ficar longos para evitar colisão (reservas-api, portaria-api).

Não crie um projeto para separar níveis, nem para separar tipos de arquivo. A árvore de contenção já separa níveis, e o arranjo de pastas dentro de um projeto é livre.

Quando o caso é outra modelagem, e não outro projeto

Um projeto novo é a resposta certa enquanto tudo é a mesma realidade: o mesmo vocabulário, o mesmo público, a mesma configuração de aparência.

Quando não é — quando são duas equipes com glossários diferentes, ou dois produtos que se leem separadamente — a resposta é uma segunda modelagem, que é uma unidade maior e se publica sozinha.

Próximo passo

Aparência da modelagem.