Skip to content

ADR-90: Domínio Platform — Gateway e Contratos de Tela

ADR-90: Domínio Platform — Gateway e Contratos de Tela

Status: Aceito Data: 2026-04-24 Autor: Michael Meneses (Arquiteto)

Contexto

O domínio platform (anteriormente referido como api no discovery) é a camada de interface entre o Backend (Moodle + local_helico) e o Frontend (Plataforma HÉLICO, aplicação NextJS). Ele não possui regras de negócio nem entities persistidas — é um gateway que orquestra chamadas aos domínios de negócio e entrega contratos de tela ao frontend.

A página arquitetura/09-platform.md (Passo 10) já detalha as visões do Aluno. Este ADR consolida a arquitetura formal do gateway: responsabilidades, regras de segurança, estratégia de migração e decisões abertas.

As decisões aqui formalizadas absorvem D-47 a D-50 do BL-009 (API Discovery Review, 2026-03-31). O domínio foi renomeado de api para platform para refletir que é a camada de plataforma (gateway + contratos de tela), não apenas endpoints técnicos.


Natureza do domínio

Aspecto Platform
Aggregate Roots Nenhum
Tabelas próprias Nenhuma
Item types EAV Nenhum
Persistência Não persiste — consome e compõe dados de outros domínios
Regras de negócio Não define — delega aos domínios de negócio

Platform é stateless. Toda a lógica de estado vive nos domínios product, engine, activity e metrics.


Responsabilidades

  1. Autenticação e autorização — valida tokens Moodle, verifica permissões por Matrícula
  2. Composição multi-domínio — orquestra chamadas a engine, activity, metrics e content para montar contratos de tela
  3. Validação de entrada — valida parâmetros antes de delegar ao domínio
  4. Contrato de resposta — garante shape consistente mesmo com dados parciais (defaults, não omissão)
  5. Migração incremental — migra endpoints de external.php para controllers em extensions/platform/

Telas × Services de orquestração (absorve D-47 + R-03)

Tela Service de orquestração Domínios consumidos
Área do Aluno student_area_service engine, metrics, product
Roteiro de Estudos study_roadmap_service engine, content
Flashcards flashcard_view_service activity, content
Revisão review_view_service engine, activity
Diagnóstico diagnostic_view_service engine, activity
Desempenho performance_view_service metrics
Simulados exam_view_service activity, engine
Biblioteca Online library_view_service content
Caderno Online notebook_view_service activity
Perfil profile_view_service product, engine

Cada service de orquestração é stateless — compõe dados dos domínios, aplica formatação de tela e retorna o contrato.


Regras de segurança (absorve D-48)

# Regra Tipo
1 Todo endpoint requer token de autenticação Moodle válido permissão
2 Endpoints de leitura validam que userid pertence ao token autenticado permissão
3 Gestor acessa apenas dados de alunos vinculados ao seu produto permissão
4 Parâmetros validados antes da delegação ao domínio consistência
5 Respostas seguem contrato de tela mesmo com dados parciais (defaults, não omissão) consistência

Migração incremental (absorve D-49)

Endpoints em classes/external.php serão migrados incrementalmente para controllers em classes/extensions/platform/controller/, mantendo compatibilidade com Moodle External API.

Padrão de nomeação: {tela}_{operacao} (ex: student_area_get_courses, study_roadmap_get_modules)

Estratégia:

  1. Novo endpoint criado em controller (extensions/platform/)
  2. external.php redirecionado para o novo controller (proxy)
  3. Frontend atualizado para chamar novo endpoint
  4. Proxy removido quando frontend migrado

Decisões abertas registradas (absorve D-50)

# Item Tipo Status
1 Composição multi-domínio: no controller ou em service de orquestração? decisão validada Service de orquestração (tabela acima). Controller delega.
2 Endpoints de escrita: na API ou expostos diretamente pelos domínios? decisão futura Submissão de respostas, início de sessão — tratar por tela
3 Versionamento de contratos de API decisão futura Estratégia a definir quando frontend estabilizar
4 Estratégia de cache entre API e domínios decisão futura Afeta performance — tratar quando métricas de uso existirem

Consequências

  • Domínio platform especificado como gateway stateless — sem ARs, sem tabelas, sem EAV
  • Rename api → platform reflete melhor o papel de camada de plataforma
  • 10 services de orquestração mapeados por tela
  • 5 regras de segurança formalizadas
  • Migração incremental de external.php especificada
  • Composição multi-domínio resolvida: services de orquestração, não controllers
  • Endpoints de escrita ainda não especificados por tela
  • Versionamento de API adiado
  • Cache strategy adiada

ADRs relacionados

  • ADR-01 — Separação de responsabilidades (platform é camada de interface, não de negócio)
  • ADR-50 — Domínio Product (consumido pela Área do Aluno, Perfil)
  • ADR-60 — Domínio Engine (consumido pelo Roteiro, Diagnóstico, Simulados)
  • ADR-70 — Domínio Metrics (consumido pelo Desempenho)
  • ADR-80 — Domínio Activity (consumido por Flashcards, Revisão, Caderno Online)

Histórico

Data Evento
2026-04-24 Criado — consolida decisões da sessão 15 + absorve BL-009 D-47..D-50 + R-03
Navigation

Type to search…

↑↓ navigate↵ selectEsc close