ADR-23: Convenção de file layout em domínios e subdomínios
Status: Aceito Data: 2026-05-28 Autor: Gabriel Sousa
Contexto
O plugin local_helico organiza código por domínio em classes/extensions/<domain>/<subdomain>/. Após a refatoração DDD do domínio product (2026-04-30) e a especificação dos domínios engine, metrics, activity, platform e admin, o codebase consolidou um padrão de file layout em 6 de 7 domínios: arquivos são agrupados por kind (responsabilidade arquitetural) em subdiretórios dedicados — contract/, service/, entity/, dto/, vo/, enums/, signal/, support/, listener/, repository/, exception/.
O domínio content é o outlier. Por razões históricas (foi o primeiro domínio especificado, em 2026-04-23, antes do padrão estar estabilizado), os arquivos de content ficam flat dentro do subdomain, agrupados apenas por prefixo de nome (discipline.php, discipline_dto.php, discipline_service.php, discipline_service_interface.php).
Sintomas do desalinhamento
- Inconsistência cognitiva ao navegar entre domínios.
- Subdomains de
contentcom 15+ arquivos misturam entities, DTOs, services e interfaces sem separação visual. - Não é possível detectar gaps arquiteturais por listagem (
ls contract/evidencia ausência de contrato; grep por sufixo não). - O padrão flat conflita com a convenção PSR-4 idiomática usada em
local_middage na literatura DDD. - Refactors recentes (product, engine) já operaram no padrão tipado, criando débito de coerência.
ADRs relacionados
- ADR-22 — Convenções de domínio e pertencimento de terms
- ADR-30 — Domínio Content (arquitetura change_record, conflitos, mapa de materialização)
- ADR-50, 60, 70, 80, 90 — Domínios product, engine, metrics, activity, platform
Decisões
1. Padrão canônico: typed dirs por kind
Todo domínio organiza arquivos PHP dentro de cada subdomain agrupando por kind em subdiretório dedicado. O namespace PSR-4 reflete o path físico (local_helico\extensions\<domain>\<subdomain>\<kind>).
2. Kind dirs aceitos
| Kind dir | Conteúdo |
|---|---|
contract/ |
Interfaces — service contracts, repository contracts, ports |
service/ |
Casos de uso, application services, command handlers |
entity/ |
Entities (aggregate roots, entity_child) — modelos com identidade |
dto/ |
Data Transfer Objects — transporte entre camadas |
vo/ |
Value Objects — imutáveis, sem identidade |
enums/ |
PHP enums |
signal/ |
Eventos de domínio — payloads disparados/escutados |
listener/ |
Listeners de signals/hooks |
repository/ |
Implementações concretas de persistência |
exception/ |
Exception types específicos do subdomain |
support/ |
Helpers internos (presenters, formatters) sem categoria arquitetural |
Um kind dir é criado apenas quando há ao menos um arquivo do tipo. Subdomains pequenos não criam dirs vazios.
3. Nome de arquivo e classe
Nome do arquivo e nome da classe não mudam ao mover para kind dir. O sufixo no nome (_service, _dto, _interface) é informativo e permanece — não é redundante com o kind dir porque facilita disambiguação em uses cross-namespace e segue o estilo já adotado em engine/product/metrics.
Antes:
content/base/discipline/discipline_service.php
namespace local_helico\extensions\content\base\discipline;
class discipline_service { ... }Depois:
content/base/discipline/service/discipline_service.php
namespace local_helico\extensions\content\base\discipline\service;
class discipline_service { ... }4. Sub-subdomains
Quando um sub-subdomain existir (ex: content.base.bank_question), a hierarquia de kind dirs aplica dentro do sub-subdomain, não acima. Sub-subdomains são tratados como qualquer subdomain.
5. Preservação de estruturas internas legítimas
Subtrees que representam pipeline interno ou agrupamento técnico (não um kind arquitetural) são preservados dentro de service/. Exemplos:
content.management.file_word.processing/— pipeline de processamento Word comcontext/,engine/,processor/,document_source/— preserva estrutura interna após mover sobservice/processing/.content.management.integration/— integrações externas (law_school/,sharepoint/) — preserva estrutura interna.
A regra: kind dirs no nível do subdomain; subtrees técnicas internas mantidas dentro do kind dir apropriado.
6. Eventos soltos no subdomain
Signals que não pertencem a um sub-subdomain específico ficam em <subdomain>/signal/. Exemplo: content/change/content_conflict_detected.php → content/change/signal/content_conflict_detected.php.
7. Files no root do domínio
Arquivos no root do domínio (não em subdomain), como <domain>_extension.php e <domain>_hooks.php, permanecem no root sem kind dir. São arquivos de wiring/registro do plugin, não componentes de domínio.
Justificativa
- Consistência: 6/7 domínios já operam neste padrão. Aplicar a
contentelimina o outlier. - Enforcement por dir: listar
contract/evidencia gaps; sufixo no nome não evidencia. - PSR-4 idiomático: namespace reflete intenção arquitetural, não apenas localização.
- Compatibilidade com refactors recentes: alinha com 2026-04-30 (product DDD refactor).
- Escalabilidade: subdomains crescem (
content.base.bank_questioné exemplo); typed dirs absorvem crescimento sem perda de discoverability.
Trade-offs aceitos
- Custo de migração de
content: ~143 arquivos PHP a mover. Mitigado por faseamento (change → base → management) e PSR-4 auto-resolve de namespaces. - Profundidade de path adicional: mais um nível de diretório. Aceitável pela legibilidade ganha.
- Sufixo redundante no nome:
service/discipline_service.phprepete a palavraservice. Mantido por simetria com domínios existentes e para evitar diff massivo de renomes de classe.
Consequências
Diretas
- Migração de
contentem 4 fases (change → base → management → raiz), formalizada em plan separado. - Atualização de
ddd-config.yamlpara refletir o padrão tipado quando o codegen LinkML evoluir. - Nenhum impacto em runtime — apenas reorganização física + namespace shift resolvido por PSR-4.
Para novos domínios
Qualquer novo subdomain criado a partir desta data segue typed dirs. PRs que criam arquivos em layout flat dentro de domínio existente são revisados como débito.
Para o codegen LinkML
O generator deve emitir arquivos diretamente em kind dirs. ADR-20 (Pipeline terms→LinkML→PHP) é atualizado em PR separado para refletir.
Referências
- ADR-22 — Convenções de domínio
- ADR-20 — Pipeline terms→LinkML→PHP (a atualizar)
- ADR-30 — Domínio Content (arquitetura)
- Plan de migração:
docs/_archive/plans/2026-05-28-content-typed-dirs-migration.md(a criar na Fase 2)