Skip to content

ADR - Architecture Decision Records

ADR - Architecture Decision Records

Objetivo

Este diretório centraliza os Architecture Decision Records (ADRs) do local_helico.

Os ADRs registram decisões arquiteturais e de modelagem do projeto, considerando que o local_helico é construído sobre o local_middag e adota SOLID, DDD pragmático e orientação a eventos como diretrizes fundacionais.


Escopo

Os ADRs tratam de decisões específicas da HÉLICO:

  • modelagem do domínio pedagógico
  • separação entre regra pedagógica, orquestração e infraestrutura
  • ciclo de vida do conteúdo (configuração, compilação, instanciação, execução)
  • fronteira entre domínio e plataforma (Moodle / local_middag)
  • comunicação entre componentes via eventos
  • estratégias de persistência (EAV próprio, tabelas, versionamento)
  • pipeline de geração de código (terms → LinkML → PHP)

Decisões fundacionais do local_middag não são duplicadas aqui — apenas referenciadas quando houver dependência.


Relação com o local_middag

  • O middag é a camada de infraestrutura e orquestração usada pelo HÉLICO
  • ADRs do local_helico podem especializar decisões do local_middag
  • ADRs do local_helico não devem contradizer ADRs do local_middag
  • Dependências devem ser registradas na seção ADRs relacionados

Formato adotado

Formato alinhado ao local_middag:

# ADR-NN: Título da decisão

**Status:** Aceito
**Data:** YYYY-MM-DD

## Contexto

## Decisão

## Consequências

+ Positivas
- Negativas

## ADRs relacionados

## Histórico

Meta: 50–130 linhas por ADR (consolidações podem exceder). Curto, técnico, orientado à decisão. Consequências com +/-.

Nome dos arquivos

adr-{NN}_{titulo-em-kebab-case}.md
ref-{NN}-{letra}_{titulo-em-kebab-case}.md

Método de trabalho

  1. 1 ADR por decisão arquitetural distinta — não subdividir por domínio quando o conteúdo é o mesmo
  2. REFs para especificação de implementação — pseudocódigo, algoritmos, critérios de aceitação
  3. Cada ADR é autocontido — não depender de leitura de outro ADR para entender o contexto
  4. Consolidações preservam a seção “Histórico” — lista de ADRs antigos que foram absorvidos, com data
  5. Numeração fixa — uma vez publicado, o número não muda
  6. Status: Rascunho → Aceito → Substituído (nunca deletar, marcar como substituído)

Faixas de numeração

Faixa Escopo
01–09 Princípios Arquiteturais
10–19 Persistência e Infraestrutura
20–29 Pipeline, Tooling e Convenções
30–39 Domínio Content
40–49 Domínio Product (product, product.learning_path, product.commercial)
50–59 Domínio Product — Aggregate Roots e contratos
60–69 Domínio Engine (engine.plan, engine.access, engine.algorithm, etc.)
70–79 Domínio Metrics
80–89 Domínio Activity (activity.assessment, activity.productive, etc.)
90–99 Domínio API (gateway, orquestração de telas)

ADRs vigentes

I. Princípios Arquiteturais (01–09)

ADR Título Status REF
01 Separação de responsabilidades e fronteira com middag Aceito —
02 Ciclo de vida pedagógico em 4 fases Aceito —
03 Abstração seletiva e hierarquia de atividades Aceito —
04 Eventos para desacoplamento entre componentes Aceito —
05 Contratos de interface para tipos polimórficos Aceito —

II. Persistência e Infraestrutura (10–19)

ADR Título Status REF
10 Persistência EAV própria e critérios de uso Aceito —
11 Versionamento por snapshot imutável Aceito —

III. Pipeline, Tooling e Convenções (20–29)

ADR Título Status REF
20 Pipeline terms → LinkML → PHP Aceito —
21 Contratos JSON para validação de entities Aceito —
22 Convenções de domínio e pertencimento de terms Aceito —
23 Convenção de file layout em domínios e subdomínios Aceito —

IV. Domínio Content (30–39)

ADR Título Status REF
30 Domínio Content — Arquitetura e Materialização Aceito REF-30-A, REF-30-B, REF-30-C/D/E

V. Domínio Product (40–59)

ADR Título Status REF
40 Configuração por Preset e invariantes do Produto Aceito REF-40-A, REF-40-B
50 Domínio Product — Arquitetura e Aggregate Roots Aceito REF-50-A

VI. Domínio Engine (60–69)

ADR Título Status REF
60 Domínio Engine — Arquitetura e Aggregate Roots Aceito REF-60-A

VII. Domínio Metrics (70–79)

ADR Título Status REF
70 Domínio Metrics — Arquitetura e Aggregate Roots Aceito REF-70-A

VIII. Domínio Activity (80–89)

ADR Título Status REF
80 Domínio Activity — Arquitetura e Aggregate Roots Aceito REF-80-A

IX. Domínio Platform (90–99)

ADR Título Status REF
90 Domínio Platform — Gateway e Contratos de Tela Aceito REF-90-A
91 Lexical state e autosave incremental no Estudo Dirigido Aceito —

REFs vigentes

Persistência e Infraestrutura

REF Título ADR Localização
REF-04-A Catálogo de Eventos Cross-Domain ADR-04 ref/ref-04-a_catalogo-de-eventos.md
REF-10-B Mapeamento de TYPE constants (EAV) ADR-10 ref/ref-10-b_mapeamento-type-eav.md
REF-10-C Table-Aware Query Engine — Spec ADR-10 ref/ref-10-c_table-aware-query-engine-spec.md
REF-10-D Mapa de Storage por Entity ADR-10 ref/ref-10-d_mapa-storage-por-entity.md

Domínio Content

REF Título ADR Localização
REF-30-A Pipeline de Processamento de Conteúdo ADR-30 ref-30-a_pipeline-de-processamento-de-conteudo.md
REF-30-B Algoritmo de Detecção de Conflitos Pedagógicos ADR-30 ref-30-b_algoritmo-de-deteccao-de-conflitos.md
REF-30-C Mapa term → subdomain → classificação ADR-30 ref/ref-30-c_content-subdomain-map.md
REF-30-D Inventário entity / attribute / VO ADR-30 ref/ref-30-d_entity-attribute-inventory.md
REF-30-E Especificação dos contratos de interface ADR-30 ref/ref-30-e_contract-specifications.md

Domínio Product

REF Título ADR Localização
REF-40-A Regras condicionais do config_json ADR-40 ref-40-a_regras-condicionais-do-config-json.md
REF-40-B Invariantes operacionais do CRE ADR-40 ref-40-b_invariantes-operacionais-do-cre.md
REF-50-A Mapeamento de enums da Sequence do plan ADR-50 ref/ref-50-a_mapeamento-enums-sequence.md

Domínio Engine

REF Título ADR Localização
REF-60-A Mapeamento de enums do Engine ADR-60 ref/ref-60-a_mapeamento-enums-engine.md

Domínio Metrics

REF Título ADR Localização
REF-70-A Mapeamento de enums do Metrics ADR-70 ref/ref-70-a_mapeamento-enums-metrics.md

Domínio Activity

REF Título ADR Localização
REF-80-A Mapeamento de enums do Activity ADR-80 ref/ref-80-a_mapeamento-enums-activity.md

Domínio Platform

REF Título ADR Localização
REF-90-A Premissas e Padrões dos Contratos API do Aluno ADR-90 ref-90-a_premissas-contratos-api-aluno.md

ADRs substituídos (arquivo)

Os ADRs abaixo foram consolidados na reorganização de 2026-04-23 e marcados como Substituído. Mantidos para rastreabilidade.

Antigo Título Substituído por
ADR-101 Separar regra pedagógica de orquestração e infraestrutura ADR-01
ADR-102 Aplicar abstração seletiva em pontos de variação pedagógica ADR-03
ADR-103 Ciclo de vida em 4 fases ADR-02
ADR-104 Fronteira regra pedagógica e infraestrutura middag ADR-01
ADR-105 Priorizar eventos para minimizar acoplamento ADR-04
ADR-106 EAV próprio em local_helico ADR-10
ADR-107 Hierarquia Atividade-base + Formato de Execução ADR-03
ADR-108 Critérios para tabela própria vs EAV ADR-10
ADR-109 Estratégia de versionamento snapshot imutável ADR-11
ADR-201 Organização do domínio Content em subdomains ADR-30
ADR-202 Entity vs attribute na Base de Conteúdo ADR-30
ADR-203 Contratos de interface para tipos polimórficos ADR-05
ADR-901 Pipeline terms→LinkML→PHP ADR-20
ADR-902 Contratos JSON para validação de entities ADR-21
ADR-903 Arquitetura change record e conflitos ADR-30
ADR-904 Mapa de materialização do domínio content ADR-30
ADR-905 Convenções de domínio e pertencimento de terms ADR-22

Ordem de leitura

  1. ADR-01 — separação de responsabilidades e fronteira com middag
  2. ADR-02 — ciclo de vida pedagógico em 4 fases
  3. ADR-03 — abstração seletiva e hierarquia de atividades
  4. ADR-04 — eventos para desacoplamento
  5. ADR-05 — contratos de interface polimórficos
  6. ADR-10 — persistência EAV e critérios de uso → REF-10-B (mapeamento TYPE)
  7. ADR-11 — versionamento por snapshot imutável
  8. ADR-20 — pipeline terms → LinkML → PHP
  9. ADR-21 — contratos JSON para entities
  10. ADR-22 — convenções de domínio
  11. ADR-23 — convenção de file layout em domínios e subdomínios
  12. ADR-30 — domínio content → REF-30-A/B/C/D/E
  13. ADR-40 — configuração por preset → REF-40-A/B
  14. ADR-50 — domínio product → REF-50-A
  15. ADR-60 — domínio engine → REF-60-A
  16. ADR-70 — domínio metrics → REF-70-A
  17. ADR-80 — domínio activity → REF-80-A
  18. ADR-90 — domínio platform (gateway)
  19. ADR-91 — Lexical state e autosave incremental no Estudo Dirigido

Critérios para criar um ADR

Um ADR deve ser criado quando a decisão:

  • afeta o domínio pedagógico ou a modelagem
  • define ou restringe organização de componentes
  • cria ponto de extensão relevante
  • define estratégia de persistência ou versionamento
  • depende de ADR do local_middag
  • altera o pipeline de geração de código

Não é necessário ADR para detalhes de implementação. Detalhes de implementação vão em REFs vinculados ao ADR.


Status permitidos

  • Aceito
  • Rascunho
  • Em revisão
  • Substituído
Navigation

Type to search…

↑↓ navigate↵ selectEsc close