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_helicopodem especializar decisões dolocal_middag - ADRs do
local_heliconão devem contradizer ADRs dolocal_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óricoMeta: 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}.mdMétodo de trabalho
- 1 ADR por decisão arquitetural distinta — não subdividir por domínio quando o conteúdo é o mesmo
- REFs para especificação de implementação — pseudocódigo, algoritmos, critérios de aceitação
- Cada ADR é autocontido — não depender de leitura de outro ADR para entender o contexto
- Consolidações preservam a seção “Histórico” — lista de ADRs antigos que foram absorvidos, com data
- Numeração fixa — uma vez publicado, o número não muda
- 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
- ADR-01 — separação de responsabilidades e fronteira com middag
- ADR-02 — ciclo de vida pedagógico em 4 fases
- ADR-03 — abstração seletiva e hierarquia de atividades
- ADR-04 — eventos para desacoplamento
- ADR-05 — contratos de interface polimórficos
- ADR-10 — persistência EAV e critérios de uso → REF-10-B (mapeamento TYPE)
- ADR-11 — versionamento por snapshot imutável
- ADR-20 — pipeline terms → LinkML → PHP
- ADR-21 — contratos JSON para entities
- ADR-22 — convenções de domínio
- ADR-23 — convenção de file layout em domínios e subdomínios
- ADR-30 — domínio content → REF-30-A/B/C/D/E
- ADR-40 — configuração por preset → REF-40-A/B
- ADR-50 — domínio product → REF-50-A
- ADR-60 — domínio engine → REF-60-A
- ADR-70 — domínio metrics → REF-70-A
- ADR-80 — domínio activity → REF-80-A
- ADR-90 — domínio platform (gateway)
- 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
AceitoRascunhoEm revisãoSubstituído