Ir para o conteúdo

Dependências entre Documentos


Grafo de Dependências

service.yaml
 ├── referencia → openapi.yaml
 ├── referencia → SLA document
 └── referencia → SRC-BR-xxx, DATA-BR-xxx

openapi.yaml
 ├── depende → DATA-BR-xxx (schemas)
 └── define  → EP-BR-xxx (endpoints)

DATA-BR-xxx
 ├── depende       → SRC-BR-xxx (origem)
 ├── contem        → FIELD-BR-xxx
 └── processado_por → PIPE-BR-xxx

SLA document
 ├── define     → SLO values
 ├── referencia → SVC-BR-xxx
 └── depende    → SLI measurements

INC-YYYY-XXXX
 └── pode_gerar → CHG-YYYY-XXXX
                  └── pode_gerar → REL-YYYY-XXXX

Diagrama de Dependências

graph TD
    SRC["SRC-BR-xxx<br/>(fonte de dados)"]
    PIPE["PIPE-BR-xxx<br/>(pipeline)"]
    DATA["DATA-BR-xxx<br/>(dataset)"]
    FIELD["FIELD-BR-xxx<br/>(campos)"]
    OAS["openapi.yaml"]
    SVC["service.yaml<br/>(Service Master Record)"]
    SLA["SLA document"]
    SLO["SLO / SLI"]
    INC["INC-YYYY-XXXX<br/>(incidente)"]
    CHG["CHG-YYYY-XXXX<br/>(mudança)"]
    REL["REL-YYYY-XXXX<br/>(release)"]

    SRC --> PIPE
    PIPE --> DATA
    DATA --> FIELD
    DATA --> OAS
    OAS --> SVC
    SLA --> SVC
    SLA --> SLO
    INC -->|pode gerar| CHG
    CHG -->|pode gerar| REL

Ordem de Criação Recomendada

# Artefato Motivo
1 Estrutura da Organization (GitHub) Tudo parte daqui
2 Templates (api-template) Base para os repositórios seguintes
3 ADR-0001 Documentar a decisão de arquitetura antes de implementar
4 LICENSE Escolher antes de publicar qualquer código
5 SRC-BR-xxx (sources) Dados primeiro — identificar origem antes de modelar
6 DATA-BR-xxx (datasets) Definir dados antes de codificar endpoints
7 openapi.yaml Spec first — o contrato precede a implementação
8 service.yaml Service Master Record referencia a spec e os dados
9 README.md Para o usuário externo — depois de ter algo a dizer
10 SECURITY.md Antes de publicar qualquer coisa
11 POL-SEC-001 Política mínima de segurança
12 POL-ACC-001 Controle de acesso desde o início

Princípio: Dados e Contratos Antes do Código

Definir fontes de dados e especificação OpenAPI antes de escrever código.

Código pode ser refatorado sem impacto externo.

A spec e os contratos de dados são o acordo público — mudá-los tem custo para os consumidores.


Relações entre Políticas

graph LR
    POL_SEC["POL-SEC-001<br/>Segurança"]
    POL_ACC["POL-ACC-001<br/>Acesso"]
    POL_DEV["POL-DEV-001<br/>Dev Seguro"]
    POL_CHG["POL-CHG-001<br/>Mudanças"]
    POL_INC["POL-INC-001<br/>Incidentes"]
    POL_BAK["POL-BAK-001<br/>Backup"]

    POL_SEC --> POL_ACC
    POL_SEC --> POL_DEV
    POL_CHG --> POL_INC
    POL_BAK --> POL_INC

POL-SEC-001 é a política-raiz. Todas as outras políticas de segurança derivam dela ou a referenciam.


Como Registrar Dependências nos Arquivos YAML

Para que a navegação Customer → Source funcione, todo arquivo deve referenciar seus vizinhos:

# service.yaml
service:
  id: SVC-BR-001
  api: API-BR-001
  sla: SLA-BR-001
  data:
    datasets: [DATA-BR-001]
    sources: [SRC-BR-001]

# dataset.yaml
dataset:
  id: DATA-BR-001
  source: SRC-BR-001
  exposed_by: API-BR-001
  transformed_by: PIPE-BR-001

# source record
source:
  id: SRC-BR-001
  name: IBGE — Malha Municipal
  used_by: [DATA-BR-001]

Próximo passo

Com as dependências mapeadas, consulte o Quickstart — Dia 1 para as instruções operacionais de execução.